feat(issuecards): add permission checks to repository commands and add global repository configuration

.forgejo/workflows/workflow.yaml

@@ -9,13 +9,13 @@ jobs:
   lint:
     name: Lint Code (Ruff & Pylint)
     runs-on: docker
-    container: catthehacker/ubuntu:act-latest@sha256:0999d0b42deb467f6b24d3c2e3b8e9fdefdb680f9a09edde1401ac898c40bbad
+    container: catthehacker/ubuntu:act-latest@sha256:70d7485966a50a639ddab37445fd27c2f0b5086ad4959ec3bba228ed394c1928
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
 
       - name: "Setup uv"
-        uses: actions/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5
+        uses: actions/setup-uv@22695119d769bdb6f7032ad67b9bca0ef8c4a174 # v5
         with:
           version: "latest"
           enable-cache: true
@@ -35,7 +35,7 @@ jobs:
   docs:
     name: Build Documentation (MkDocs)
     runs-on: docker
-    container: catthehacker/ubuntu:act-latest@sha256:0999d0b42deb467f6b24d3c2e3b8e9fdefdb680f9a09edde1401ac898c40bbad
+    container: catthehacker/ubuntu:act-latest@sha256:70d7485966a50a639ddab37445fd27c2f0b5086ad4959ec3bba228ed394c1928
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
@@ -43,7 +43,7 @@ jobs:
           fetch-depth: 0
 
       - name: "Setup uv"
-        uses: actions/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5
+        uses: actions/setup-uv@22695119d769bdb6f7032ad67b9bca0ef8c4a174 # v5
         with:
           version: "latest"
           enable-cache: true

issuecards/__init__.py

@@ -0,0 +1,5 @@
+from .issuecards import IssueCards
+
+
+async def setup(bot):
+    await bot.add_cog(IssueCards(bot))

issuecards/api/__init__.py

@@ -0,0 +1,3 @@
+from .wrapper import fetch_issue
+
+__all__ = ["fetch_issue"]

issuecards/api/forgejo.py

@@ -0,0 +1,70 @@
+import aiohttp
+
+from ..logger import logger
+from ..models import Issue, Repository
+
+
+async def fetch_forgejo_issue(repository: Repository, issue_number: int) -> Issue:
+    """
+    Fetch an issue from a Forgejo instance.
+    Args:
+        repository (Repository): The repository to fetch the issue from.
+        issue_number (int): The issue number.
+    Returns:
+        Issue: An Issue object containing the issue details.
+    Raises:
+        aiohttp.ClientResponseError: If the request to the Forgejo API fails.
+        ValueError: If the response from the Forgejo API is empty
+    """
+    headers: dict[str, str] = {"User-Agent": repository.user_agent}
+    if repository.provider.token is not None:
+        headers["Authorization"] = f"token {repository.provider.token}"
+    else:
+        logger.info("Forgejo API key is not set for provider '%s'. Using unauthenticated request.", repository.provider.url)
+    url = f"{repository.provider.api_url}/repos/{repository.owner}/{repository.name}/issues/{issue_number}"
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url, headers=headers) as response:
+            if response.status != 200:
+                raise aiohttp.ClientResponseError(
+                    request_info=response.request_info,
+                    history=response.history,
+                    status=response.status,
+                    message=f"Failed to fetch issue '{issue_number}' from '{repository.url}'.",
+                )
+            data = await response.json()
+
+    if data is None:
+        raise ValueError("Received empty response from Forgejo API.")
+
+    pull_request = data.get("pull_request")
+    if pull_request is not None:
+        if pull_request["merged"] is True:
+            issue_type = "pull_request_merged"
+        elif pull_request["draft"] is True:
+            issue_type = "pull_request_draft"
+        elif data.get("state", "open") == "closed":
+            issue_type = "pull_request_closed"
+        else:
+            issue_type = "pull_request"
+    elif data.get("state", "open") == "closed":
+        issue_type = "issue_closed"
+    else:
+        issue_type = "issue"
+
+    return Issue(
+        repository=repository,
+        number=data["number"],
+        author=data["user"]["login"],
+        author_avatar=data["user"]["avatar_url"],
+        author_url=data["user"]["html_url"],
+        link=data["html_url"],
+        title=data["title"],
+        body=data["body"] or "",
+        type=issue_type,
+        labels=[label["name"] for label in data.get("labels", [])],
+        draft=bool(data["pull_request"].get("draft", False) if data.get("pull_request") is not None else False),
+        creation_date=data["created_at"],
+        milestone=data.get("milestone", {}).get("title") if data.get("milestone") is not None else None,
+        merge_date=data.get("pull_request").get("merged_at") if data.get("pull_request") is not None else None,
+        response=response,
+    )

issuecards/api/github.py

@@ -0,0 +1,204 @@
+import aiohttp
+
+from ..logger import logger
+from ..models import Issue, Repository
+
+
+def _populate_headers(repository: Repository) -> dict[str, str]:
+    headers: dict[str, str] = {"User-Agent": repository.user_agent, "X-GitHub-Api-Version": "2022-11-28"}
+    if repository.provider.token is not None:
+        headers["Authorization"] = f"Bearer {repository.provider.token}"
+    else:
+        logger.debug("GitHub API key is not set for provider '%s'. Using unauthenticated request.", repository.provider.url)
+    return headers
+
+
+async def fetch_github_issue(repository: Repository, issue_number: int) -> Issue:
+    """
+    Fetch an issue from a GitHub instance.
+    If the issue cannot be fetched because it isn't an issue or pull request, this function will try to find a discussion within the same repository with the given number.
+    Args:
+        repository (Repository): The repository to fetch the issue from.
+        issue_number (int): The issue number.
+    Returns:
+        Issue: An Issue object containing the issue details.
+    Raises:
+        aiohttp.ClientResponseError: If the request to the GitHub API fails.
+        ValueError: If the response from the GitHub API is empty.
+    """
+    url = f"{repository.provider.api_url}/repos/{repository.owner}/{repository.name}/issues/{issue_number}"
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url, headers=_populate_headers(repository)) as response:
+            match response.status:
+                case 200:
+                    pass
+                case 404:
+                    return await _fetch_github_discussion(repository, issue_number)
+                case _:
+                    raise aiohttp.ClientResponseError(
+                        request_info=response.request_info,
+                        history=response.history,
+                        status=response.status,
+                        message=f"Failed to fetch issue '{issue_number}' from '{repository.url}'.",
+                    )
+            data = await response.json()
+
+    if data is None:
+        raise ValueError("Received empty response from the GitHub API.")
+
+    pull_request = data.get("pull_request")
+    if pull_request is not None:
+        if pull_request.get("merged_at") is not None:
+            issue_type = "pull_request_merged"
+        elif data.get("draft", False) is True:
+            issue_type = "pull_request_draft"
+        elif data.get("state", "open") == "closed":
+            issue_type = "pull_request_closed"
+        else:
+            issue_type = "pull_request"
+    elif data.get("state", "open") == "closed":
+        state_reason = data.get("state_reason", "completed")
+        if state_reason in ["not_planned", "duplicate"]:
+            issue_type = "issue_not_planned"
+        else:
+            issue_type = "issue_closed"
+    else:
+        issue_type = "issue"
+
+    return Issue(
+        repository=repository,
+        number=data["number"],
+        author=data["user"]["login"],
+        author_avatar=data["user"]["avatar_url"],
+        author_url=data["user"]["html_url"],
+        link=data["html_url"],
+        title=data["title"],
+        body=data["body"],
+        type=issue_type,
+        labels=[label["name"] for label in data.get("labels", [])],
+        draft=data.get("draft", False),
+        creation_date=data["created_at"],
+        milestone=data.get("milestone", {}).get("title") if data.get("milestone") is not None else None,
+        milestone_url=data.get("milestone", {}).get("html_url") if data.get("milestone") is not None else None,
+        merge_date=data.get("pull_request").get("merged_at") if data.get("pull_request") is not None else None,
+        response=response,
+    )
+
+
+async def _fetch_github_discussion(repository: Repository, discussion_number: int) -> Issue:
+    url = f"{repository.provider.api_url}/repos/{repository.owner}/{repository.name}/discussions/{discussion_number}"
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url, headers=_populate_headers(repository)) as response:
+            match response.status:
+                case 200:
+                    pass
+                case _:
+                    raise aiohttp.ClientResponseError(
+                        request_info=response.request_info,
+                        history=response.history,
+                        status=response.status,
+                        message=f"Failed to fetch discussion {discussion_number} from {repository.owner}/{repository.name}",
+                    )
+            data = await response.json()
+    if data is None:
+        raise ValueError("Received empty response from GitHub API.")
+
+    if data.get("state", "open") == "closed":
+        state_reason = data.get("state_reason", "completed")
+        if state_reason == "duplicate":
+            discussion_type = "discussion_duplicate"
+        elif state_reason == "outdated":
+            discussion_type = "discussion_outdated"
+        else:
+            discussion_type = "discussion_closed"
+    else:
+        answer = data.get("answer_chosen_by")
+        if answer is not None:
+            discussion_type = "discussion_answered"
+        else:
+            discussion_type = "discussion"
+
+    return Issue(
+        repository=repository,
+        number=discussion_number,
+        author=data["user"]["login"],
+        author_avatar=data["user"]["avatar_url"],
+        author_url=data["user"]["html_url"],
+        link=data["html_url"],
+        title=data["title"],
+        body=data["body"],
+        type=discussion_type,
+        labels=[label["name"] for label in data.get("labels", [])],
+        draft=False,
+        creation_date=data["created_at"],
+        response=response,
+    )
+
+
+# async def fetch_github_issue(repository: Repository, issue_number: int) -> Issue:
+#     """
+#     Fetch an issue from a GitHub instance.
+#     If the issue cannot be fetched because it isn't an issue or pull request, this function will try to find a discussion within the same repository with the given number.
+#     Args:
+#         repository (Repository): The repository to fetch the issue from.
+#         issue_number (int): The issue number.
+#     Returns:
+#         Issue: An Issue object containing the issue details.
+#     """
+#     query = gql(
+#         f"""
+#     {{
+#         repository(owner: "{repository.owner}", name: "{repository.name}") {{
+#             issueOrPullRequest(number: {issue_number}) {{
+#                 ... on Issue {{
+#                     title
+#                     body
+#                     author {{
+#                         login
+#                         avaturUrl
+#                         url
+#                     }}
+#                     url
+#                     issueState: state
+#                     labels(first: 10) {{
+#                         nodes {{
+#                             name
+#                         }}
+#                     }}
+#                     createdAt
+#                     milestone {{
+#                         title
+#                         url
+#                     }}
+#                 }}
+#                 ... on PullRequest {{
+#                     title
+#                     body
+#                     author {{
+#                         login
+#                         avaturUrl
+#                         url
+#                     }}
+#                     url
+#                     pullRequestState: state
+#                     labels(first: 10) {{
+#                         nodes {{
+#                             name
+#                         }}
+#                     }}
+#                     createdAt
+#                     milestone {{
+#                         title
+#                         url
+#                     }}
+#                     mergedAt
+#                 }}
+#             }}
+#         }}
+#     }}
+#     """,
+#     )
+#     transport = AIOHTTPTransport(url=repository.provider.graphql_url, headers=_populate_headers(repository))
+#     async with Client(transport=transport, fetch_schema_from_transport=True) as client:
+#         response = await client.execute(query)
+#     return response

issuecards/api/gitlab.py

@@ -0,0 +1,119 @@
+import aiohttp
+
+from ..logger import logger
+from ..models import Issue, Repository
+
+
+def _populate_headers(repository: Repository) -> dict[str, str]:
+    headers: dict[str, str] = {"User-Agent": repository.user_agent}
+    if repository.provider.token is not None:
+        headers["Authorization"] = f"Bearer {repository.provider.token}"
+    else:
+        logger.debug("GitLab API key is not set for provider '%s'. Using unauthenticated request.", repository.provider.url)
+    return headers
+
+
+async def fetch_gitlab_issue(repository: Repository, issue_number: int) -> Issue:
+    """
+    Fetch an issue from a GitLab instance.
+    Args:
+        repository (Repository): The repository to fetch the issue from.
+        issue_number (int): The issue number.
+    Returns:
+        Issue: An Issue object containing the issue details.
+    Raises:
+        aiohttp.ClientResponseError: If the request to the Forgejo API fails.
+        ValueError: If the response from the Forgejo API is empty
+    """
+    url = f"{repository.provider.api_url}/projects/{repository.owner}%2F{repository.name}/issues/{issue_number}"
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url, headers=_populate_headers(repository)) as response:
+            if response.status != 200:
+                raise aiohttp.ClientResponseError(
+                    request_info=response.request_info,
+                    history=response.history,
+                    status=response.status,
+                    message=f"Failed to fetch issue '{issue_number}' from '{repository.url}'.",
+                )
+            data = await response.json()
+
+    if data is None:
+        raise ValueError("Received empty response from the GitLab API.")
+
+    if data.get("state", "opened") == "closed":
+        issue_type = "issue_closed"
+    else:
+        issue_type = "issue"
+
+    return Issue(
+        repository=repository,
+        number=data["iid"],
+        author=data["author"]["username"],
+        author_avatar=data["author"]["avatar_url"],
+        author_url=data["author"]["web_url"],
+        link=data["web_url"],
+        title=data["title"],
+        body=data["description"],
+        type=issue_type,
+        labels=data.get("labels", []),
+        draft=False,
+        creation_date=data["created_at"],
+        milestone=data.get("milestone", {}).get("title") if data.get("milestone") is not None else None,
+        response=response,
+    )
+
+
+async def fetch_gitlab_merge_request(repository: Repository, merge_request_number: int) -> Issue:
+    """
+    Fetch a merge request from a GitLab instance.
+    Args:
+        repository (Repository): The repository to fetch the merge request from.
+        merge_request_number (int): The merge request number.
+    Returns:
+        Issue: An Issue object containing the merge request details.
+    Raises:
+        aiohttp.ClientResponseError: If the request to the GitLab API fails.
+        ValueError: If the response from the GitLab API is empty
+    """
+    url = f"{repository.provider.api_url}/projects/{repository.owner}%2F{repository.name}/merge_requests/{merge_request_number}"
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url, headers=_populate_headers(repository)) as response:
+            if response.status != 200:
+                raise aiohttp.ClientResponseError(
+                    request_info=response.request_info,
+                    history=response.history,
+                    status=response.status,
+                    message=f"Failed to fetch merge request '{merge_request_number}' from '{repository.url}'.",
+                )
+            data = await response.json()
+
+    if data is None:
+        raise ValueError("Received empty response from the GitLab API.")
+
+    state = data.get("state", "opened")
+    if state == "merged":
+        issue_type = "pull_request_merged"
+    elif state == "closed":
+        issue_type = "pull_request_closed"
+    elif data.get("draft", False) is True:
+        issue_type = "pull_request_draft"
+    else:
+        issue_type = "pull_request"
+
+    return Issue(
+        repository=repository,
+        number=data["iid"],
+        author=data["author"]["username"],
+        author_avatar=data["author"]["avatar_url"],
+        author_url=data["author"]["web_url"],
+        link=data["web_url"],
+        title=data["title"],
+        body=data["description"],
+        type=issue_type,
+        labels=data.get("labels", []),
+        draft=data.get("draft", False),
+        creation_date=data["created_at"],
+        milestone=data.get("milestone", {}).get("title") if data.get("milestone") is not None else None,
+        merge_date=data.get("merged_at"),
+        response=response,
+    )

issuecards/api/wrapper.py

@@ -0,0 +1,22 @@
+from ..models import Issue, Repository
+from .forgejo import fetch_forgejo_issue
+from .github import fetch_github_issue
+from .gitlab import fetch_gitlab_issue, fetch_gitlab_merge_request
+
+
+async def fetch_issue(repository: Repository, issue_number: int, gitlab_issue_type: str = "issue") -> Issue:
+    match repository.provider.service:
+        case "github":
+            if gitlab_issue_type == "merge_request":
+                raise ValueError("Wrong provider!")
+            return await fetch_github_issue(repository, issue_number)
+        case "forgejo":
+            if gitlab_issue_type == "merge_request":
+                raise ValueError("Wrong provider!")
+            return await fetch_forgejo_issue(repository, issue_number)
+        case "gitlab":
+            if gitlab_issue_type == "merge_request":
+                return await fetch_gitlab_merge_request(repository, issue_number)
+            return await fetch_gitlab_issue(repository, issue_number)
+        case _:
+            raise ValueError("Unsupported provider service: '%s'" % repository.provider.service)

issuecards/config.py

@@ -0,0 +1,32 @@
+from redbot.core import Config
+
+config: Config = Config.get_conf(None, identifier=294518358420750336, cog_name="IssueCards", force_registration=True)
+
+
+def register_config(config_obj: Config) -> None:
+    """Register the cog configuration with the given config object.
+
+    Provider structure:
+        {
+            "id": "unique identifier for the provider",
+            "url": "url + scheme to access the provider",
+            "service": "service type of the provider (e.g., `github`, `gitlab`, `forgejo`)",
+            "token": "api token for the provider, not required (unauthenticated requests will be used instead if this is not provided)",
+        }
+
+    Repository structure:
+        {
+            "owner": "owner of the repository",
+            "name": "name of the repository",
+            "provider": "provider ID that contains this repository. requires a provider to exist with the same ID",
+            "prefix": "prefix used for determining which repository to retrieve an issue from when using the `#<issue-num>` syntax"
+        }
+    """
+    config_obj.register_global(
+        global_providers=[{"id": "github", "url": "https://github.com", "service": "github", "token": None}, {"id": "gitlab", "url": "https://gitlab.com", "service": "gitlab", "token": None}],
+        global_repositories=[],  # {"owner": "Cog-Creators","repository": "Red-DiscordBot", "provider": "github", "prefix": "red"}
+    )
+    config_obj.register_guild(
+        providers=[],
+        repositories=[],
+    )

issuecards/constants.py

@@ -0,0 +1,30 @@
+from discord import Colour
+
+COLORS = {
+    "done": Colour.dark_purple(),
+    "success": Colour.green(),
+    "muted": Colour.greyple(),
+    "danger": Colour.red(),
+}
+
+TYPES = [
+    {"name": "issue", "octicon": "issue-opened", "color": COLORS["success"]},
+    {"name": "issue_closed", "octicon": "issue-closed", "color": COLORS["done"]},
+    {"name": "issue_not_planned", "octicon": "skip", "color": COLORS["muted"]},
+    {"name": "issue_draft", "octicon": "issue-draft", "color": COLORS["muted"]},
+    {"name": "pull_request", "octicon": "git-pull-request", "color": COLORS["success"]},
+    {"name": "pull_request_closed", "octicon": "git-pull-request-closed", "color": COLORS["danger"]},
+    {"name": "pull_request_draft", "octicon": "git-pull-request-draft", "color": COLORS["muted"]},
+    {"name": "pull_request_merged", "octicon": "git-merge", "color": COLORS["done"]},
+    {"name": "discussion", "octicon": "comment-discussion", "color": COLORS["success"]},
+    {"name": "discussion_answered", "octicon": "discussion-closed", "color": COLORS["success"]},
+    {"name": "discussion_closed", "octicon": "discussion-closed", "color": COLORS["done"]},
+    {"name": "discussion_duplicate", "octicon": "discussion-duplicate", "color": COLORS["muted"]},
+    {"name": "discussion_outdated", "octicon": "discussion-outdated", "color": COLORS["muted"]},
+]
+
+TYPES_LIST = [octicon["name"] for octicon in TYPES]
+
+
+def convert_name(name: str) -> str:
+    return f"issuecards_{name.replace('-', '_').replace('git_', '')}"

issuecards/info.json

@@ -0,0 +1,13 @@
+{
+  "author": ["cswimr"],
+  "install_msg": "Thank you for installing IssueCards!\nYou can find the source code of this cog [here](https://c.csw.im/cswimr/SeaCogs).",
+  "name": "IssueCards",
+  "short": "",
+  "description": "",
+  "end_user_data_statement": "This cog does not store end user data.",
+  "hidden": false,
+  "disabled": false,
+  "min_bot_version": "3.5.17",
+  "min_python_version": [3, 10, 0],
+  "tags": ["git", "github", "forgejo", "gitea", "gitlab"]
+}

issuecards/issuecards.py

@@ -0,0 +1,327 @@
+import re
+from io import BytesIO
+
+import numpy as np
+from cairosvg import svg2png
+from discord import Embed, Emoji, Message
+from PIL import Image
+from pyocticons import octicon
+from redbot.core.bot import Red, commands
+from redbot.core.utils.chat_formatting import bold, humanize_list, inline
+from redbot.core.utils.views import SimpleMenu
+from typing_extensions import override
+
+from .api import fetch_issue
+from .config import config, register_config
+from .constants import TYPES, convert_name
+from .logger import logger
+from .models import Provider, Repository
+
+
+class IssueCards(commands.Cog):
+    """Post embeds for Git hosting provider issues when posting issue links or messages with an issue identifier in them (<repo>#<issue number>)"""
+
+    __author__ = ["[cswimr](https://c.csw.im/cswimr)"]
+    __git__ = "https://c.csw.im/cswimr/SeaCogs"
+    __version__ = "1.0.0"
+    __documentation__ = "https://seacogs.csw.im/issuecards/"
+
+    def __init__(self, bot: Red) -> None:
+        super().__init__()
+        self.bot: Red = bot
+        self.application_emojis: list[Emoji] = []
+        register_config(config)
+
+    @override
+    def format_help_for_context(self, ctx: commands.Context) -> str:
+        pre_processed = super().format_help_for_context(ctx) or ""
+        n = "\n" if "\n\n" not in pre_processed else ""
+        text = [
+            f"{pre_processed}{n}",
+            f"{bold('Cog Version:')} [{self.__version__}]({self.__git__})",
+            f"{bold('Author:')} {humanize_list(self.__author__)}",
+            f"{bold('Documentation:')} {self.__documentation__}",
+        ]
+        return "\n".join(text)
+
+    @override
+    async def cog_load(self) -> None:
+        await self._create_emojis()
+
+    @commands.Cog.listener("on_message_without_command")
+    async def issue_idenitifer_listener(self, message: Message) -> None:
+        """Listen for messages and check if they contain issue identifiers."""
+        if message.author.bot or not message.guild:
+            return
+
+        identifier_pattern = r"(?:(?<=\s)|(?<=^))(?P<prefix>\w+)(?P<gitlab_issue_type>#|!)(?P<issue_number>\d+)(?=$|\s)"
+        url_pattern = r"(?P<base_url>https?:\/\/[^\/]+)\/(?P<author>[^\/]+)\/(?P<repository_name>[^\/]+)(?:\/-)?\/(?P<type>issues|discussions|pull|pulls|merge_requests)\/(?P<number>\d+)"
+
+        matches = []
+        matches.extend(
+            {
+                "match_type": "identifier",
+                "prefix": match.group("prefix"),
+                "gitlab_issue_type": match.group("gitlab_issue_type"),
+                "issue_number": match.group("issue_number"),
+            }
+            for match in re.finditer(identifier_pattern, message.content)
+        )
+        matches.extend(
+            {
+                "match_type": "url",
+                "base_url": match.group("base_url"),
+                "author": match.group("author"),
+                "repository_name": match.group("repository_name"),
+                "type": match.group("type"),
+                "number": match.group("number"),
+            }
+            for match in re.finditer(url_pattern, message.content)
+        )
+
+        if not matches:
+            return
+
+        logger.debug("Found %s issue identifiers in message '%s'. Fetching issue from matches: %s", len(matches), message.id, matches)
+
+        providers = await Provider.fetch_all(guild=message.guild)
+        async with message.channel.typing():
+            first = True
+            for match in matches:
+                if match["match_type"] == "identifier":
+                    prefix = match["prefix"]
+                    gitlab_issue_type_group = match["gitlab_issue_type"]
+                    issue_number = match["issue_number"]
+
+                    if gitlab_issue_type_group == "!":
+                        gitlab_issue_type = "merge_request"
+                    else:
+                        gitlab_issue_type = "issue"
+
+                    try:
+                        repository = await Repository.from_prefix(cog=self, guild=message.guild, prefix=prefix)
+                        issue = await fetch_issue(repository, issue_number, gitlab_issue_type)
+                    except ValueError:
+                        continue
+
+                    if first is True:
+                        first = False
+                        await issue.send(message, reply=True)
+                    else:
+                        await issue.send(message)
+
+                elif match["match_type"] == "url":
+                    base_url = match["base_url"]
+                    author = match["author"]
+                    repository_name = match["repository_name"]
+                    issue_type = match["type"]
+                    number = match["number"]
+
+                    provider: Provider | None = None
+                    for p in providers:
+                        if p.url == base_url:
+                            provider = p
+                        if p.guild is not None:
+                            break
+                    if provider is None:
+                        continue
+
+                    if issue_type == "merge_requests":
+                        gitlab_issue_type = "merge_request"
+                    else:
+                        gitlab_issue_type = "issue"
+
+                    try:
+                        repository = Repository(cog=self, guild=message.guild, owner=author, name=repository_name, provider=provider)
+                        issue = await fetch_issue(repository, number, gitlab_issue_type)
+                    except ValueError:
+                        continue
+
+                    if first is True:
+                        first = False
+                        await issue.send(message, reply=True)
+                    else:
+                        await issue.send(message)
+
+    async def _create_emojis(self) -> None:
+        """Create the application emojis used for the cog."""
+
+        application_emojis: list[Emoji] = await self.bot.fetch_application_emojis()
+        all_application_emojis: list[Emoji] = application_emojis.copy()
+
+        for t in TYPES:
+            if convert_name(t["name"]) in (emoji.name for emoji in application_emojis):
+                logger.trace("Emoji '%s' already exists, skipping", t["name"])
+                continue
+            try:
+                icon = octicon(t["octicon"], 256)
+                if not icon:
+                    raise ValueError("Failed to create octicon emoji for '%s'. Does this icon name exist within octicons?" % t["octicon"])
+                rendered_emoji = BytesIO()
+                svg2png(icon, write_to=rendered_emoji)
+                image = Image.open(rendered_emoji)
+                image = image.convert("RGBA")
+                data = np.array(image)
+                red, green, blue, _alpha = data.T
+                black_areas = (red == 0) & (blue == 0) & (green == 0)
+                data[..., :-1][black_areas.T] = t["color"].to_rgb()
+                image = Image.fromarray(data)
+                with BytesIO() as emoji:
+                    image.save(emoji, "PNG")
+                    emoji.seek(0)
+                    all_application_emojis.append(await self.bot.create_application_emoji(name=convert_name(t["name"]), image=emoji.getvalue()))
+            except Exception as e:
+                logger.exception("Failed to create emoji for type '%s'", t["name"], exc_info=e)
+        self.application_emojis = all_application_emojis
+
+    @commands.group(name="issuecards")
+    async def issuecards(self, ctx: commands.Context) -> None:
+        """Manage the IssueCards cog configuration."""
+
+    @issuecards.group(name="providers")
+    async def issuecards_providers(self, ctx: commands.Context) -> None:
+        """Manage IssueCards providers."""
+
+    @issuecards_providers.command(name="list")
+    @commands.bot_has_permissions(embed_links=True)
+    async def issuecards_providers_list(self, ctx: commands.Context) -> None:
+        """List the IssueCards providers."""
+        providers = await Provider.fetch_all(guild=ctx.guild)
+        if not providers:
+            await ctx.send("No providers found.")
+            return
+
+        embed_color = await self.bot.get_embed_color(ctx.channel)
+        pages: list[Embed] = []
+        for i in range(0, len(providers), 24):
+            embed = Embed(
+                title="IssueCards Providers",
+                description="List of registered providers. Non-global providers take priority over global providers.",
+                color=embed_color,
+            )
+            embed.set_footer(text=f"Page {i // 24 + 1}/{len(providers) // 24 + 1}")
+            for provider in providers[i : i + 24]:
+                # fmt: off
+                field_value = (
+                    f"{bold('URL:')} {provider.url}\n"
+                    f"{bold('Service:')} {provider.service}\n"
+                    f"{bold('Token:')} {'Set' if provider.token else 'Not Set'}\n"
+                    f"{bold('Global:')} {'No' if provider.guild else 'Yes'}"
+                )
+                # fmt: on
+                embed.add_field(name=provider.id, value=field_value, inline=True)
+            pages.append(embed)
+
+        await SimpleMenu(pages).start(ctx, ephemeral=True)  # pyright: ignore[reportArgumentType]
+
+    @issuecards.group(name="repositories", aliases=["repository", "repo", "repos"])
+    async def issuecards_repositories(self, ctx: commands.Context) -> None:
+        """Manage IssueCards repositories."""
+
+    @issuecards_repositories.command(name="add")
+    @commands.admin_or_permissions(manage_guild=True)
+    async def issuecards_repositories_add(self, ctx: commands.Context, owner: str, name: str, provider_id: str, prefix: str | None = None, is_global: bool = False) -> None:
+        """Add a repository to the IssueCards configuration.
+
+        **Arguments**
+        * `owner`: The owner of the repository.
+        * `name`: The name of the repository.
+        * `provider_id`: The ID of the provider that contains this repository.
+          Use `[p]issuecards providers list` to get a list of valid providers.
+        * `prefix`: The prefix used for determining which repository to retrieve an issue from when using the `<prefix>#<issue-num>` syntax.
+          Defaults to `None`, disabling the prefix functionality.
+        * `is_global`: Whether the repository is global or not. If this is set to True, you must be the bot owner to create the repository.
+        """
+        if is_global is True and not await self.bot.is_owner(ctx.author):
+            await ctx.send("Only the bot owner can create global repositories.")
+            return
+
+        prefix = prefix.lower() if prefix else None
+        try:
+            provider = await Provider.from_config(provider_id, None if is_global else ctx.guild)
+        except ValueError:
+            await ctx.send(f"Invalid provider ID. Please use {inline(f'{ctx.prefix}issuecards providers list')} for a list of valid providers.")
+            return
+
+        try:
+            await Repository.from_config(cog=self, guild=ctx.guild, owner=owner, repository=name, provider_id=provider.id)
+            await ctx.send(f"Repository `{owner}/{name}` already exists in the configuration.")
+            return
+        except ValueError:
+            pass
+
+        try:
+            await Repository.from_prefix(cog=self, guild=ctx.guild, prefix=prefix or "")
+            await ctx.send(f"Repository with prefix `{prefix}` already exists in the configuration.")
+            return
+        except ValueError:
+            pass
+
+        repository = Repository(cog=self, guild=None if is_global else ctx.guild, owner=owner, name=name, provider=provider, prefix=prefix)
+        await repository.to_config()
+        await ctx.send(f"Repository `{owner}/{name}` {f'with prefix `{prefix}` ' if prefix is not None else ' '}has been added to the configuration.")
+
+    @issuecards_repositories.command(name="remove")
+    @commands.admin_or_permissions(manage_guild=True)
+    async def issuecards_repositories_remove(self, ctx: commands.Context, owner: str, name: str, provider_id: str, is_global: bool = False) -> None:
+        """Remove a repository from the IssueCards configuration.
+
+        **Arguments**
+        * `owner`: The owner of the repository.
+        * `name`: The name of the repository.
+        * `provider_id`: The ID of the provider that contains this repository.
+          Use `[p]issuecards providers list` to get a list of valid providers.
+        * `is_global`: Whether the repository is global or not. If this is set to True, you must be the bot owner to remove the repository.
+        """
+        if is_global is True and not await self.bot.is_owner(ctx.author):
+            await ctx.send("Only the bot owner can remove global repositories.")
+            return
+
+        try:
+            provider = await Provider.from_config(provider_id, ctx.guild)
+        except ValueError:
+            await ctx.send(f"Invalid provider ID. Please use {inline(f'{ctx.prefix}issuecards providers list')} for a list of valid providers.")
+            return
+
+        repository = await Repository.from_config(cog=self, guild=ctx.guild, owner=owner, repository=name, provider_id=provider.id)
+        if not repository:
+            await ctx.send(f"Repository `{owner}/{name}` does not exist in the configuration.")
+            return
+
+        if not is_global and repository.guild is None:
+            await ctx.send(f"Repository `{owner}/{name}` is a global repository. You must be the bot owner to remove it.")
+
+        await repository.remove_config()
+        await ctx.send(f"Repository `{owner}/{name}` has been removed from the configuration.")
+
+    @issuecards_repositories.command(name="list")
+    @commands.bot_has_permissions(embed_links=True)
+    async def issuecards_repositories_list(self, ctx: commands.Context) -> None:
+        """List the IssueCards repositories."""
+        repositories = await Repository.fetch_all(cog=self, guild=ctx.guild)
+        if not repositories:
+            await ctx.send("No repositories found.")
+            return
+
+        embed_color = await self.bot.get_embed_color(ctx.channel)
+        pages: list[Embed] = []
+        for i in range(0, len(repositories), 25):
+            embed = Embed(
+                title="IssueCards Repositories",
+                description="List of registered repositories.",
+                color=embed_color,
+            )
+            embed.set_footer(text=f"Page {i // 25 + 1}/{len(repositories) // 25 + 1}")
+            for repository in repositories[i : i + 25]:
+                # fmt: off
+                field_value = (
+                    f"{bold('URL:')} {repository.url}\n"
+                    f"{bold('Provider:')} {repository.provider.id}\n"
+                    f"{bold('Prefix:')} {repository.prefix or 'None'}\n"
+                    f"{bold('Global:')} {'No' if repository.guild else 'Yes'}"
+                )
+                # fmt: on
+                embed.add_field(name=f"{repository.owner}/{repository.name}", value=field_value, inline=True)
+            pages.append(embed)
+
+        await SimpleMenu(pages).start(ctx, ephemeral=True)  # pyright: ignore[reportArgumentType]

issuecards/logger.py

@@ -0,0 +1,3 @@
+from red_commons.logging import getLogger
+
+logger = getLogger("red.SeaCogs.IssueCards")

issuecards/models/__init__.py

@@ -0,0 +1,5 @@
+from .issue import Issue
+from .provider import Provider, UnsupportedServiceError
+from .repository import Repository
+
+__all__ = ["Issue", "Provider", "Repository", "UnsupportedServiceError"]

issuecards/models/issue.py

@@ -0,0 +1,223 @@
+import re
+from datetime import datetime
+from typing import Any
+
+from aiohttp import ClientResponse
+from discord import ButtonStyle, Color, Embed, Emoji, Interaction, Message, NotFound, PartialEmoji, ui
+from pydantic import BaseModel, ConfigDict, field_validator
+from redbot.core.bot import commands
+
+from ..constants import TYPES, TYPES_LIST, convert_name
+from .repository import Repository
+
+
+class Issue(BaseModel):
+    """
+    Model for provider issues. Used as an abstraction layer over the GitHub, GitLab, and Forgejo APIs, to simplify Discord-sided integration.
+    "Issue" here refers to anything that uses the normal issue numbering scheme, so this includes Pull Requests and (GitHub) Discussions.
+
+    Attributes:
+        repository (Repository): The repository the issue belongs to.
+        number (int): The issue number.
+        author (str): The author of the issue.
+        author_avatar (str): The author's avatar URL.
+        author_url (str): The author's profile URL.
+        link (str): A link to the issue.
+        title (str): The title of the issue.
+        body (str): The contents of the issue.
+        type (str): The type of issue. Can be `issue`, `pull_request`, or `discussion`.
+        draft (bool): Whether the issue is a draft. This will usually only apply to pull requests.
+        creation_date (datetime): The date the issue was created on.
+        milestone (str | None): The milestone the issue is associated with, if applicable.
+        milestone_url (str | None): The URL to the milestone, if applicable.
+        merge_date (datetime | None): The date the issue was merged, if applicable. This will usually only apply to pull requests.
+        response (aiohttp.ClientResponse | None): The raw response from the provider API, if available.
+        has_short_embed (bool): Whether the currently present message for this issue has a short embed. Defaults to False, please don't set this manually.
+        message (discord.Message | None): The message object for the issue embed, if available.
+
+    Properties:
+        color (discord.Color): The color for the embed based on the issue type.
+        emoji (discord.PartialEmoji | discord.Emoji): The emoji for the issue based on its type.
+        markdown_link (str): A Markdown-formatted link to the issue.
+        prefixed_number (str): The issue number prefixed with a `#`, or a `!` if it's a pull request and is from GitLab.
+        pretty_title (str): The title with the some extra metadata.
+        unix_timestamp (int): The creation date as a Unix timestamp.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    repository: Repository
+    number: int
+    author: str
+    author_avatar: str
+    author_url: str
+    link: str
+    title: str
+    body: str
+    type: str
+    labels: list[str] = []
+    draft: bool = False
+    creation_date: datetime
+    milestone: str | None = None
+    milestone_url: str | None = None
+    merge_date: datetime | None = None
+    response: ClientResponse | None = None
+    _has_short_embed: bool = False
+    _message: Message | None = None
+
+    @field_validator("type")
+    @classmethod
+    def _validate_type(cls, value: Any) -> Any:
+        if value not in TYPES_LIST:
+            raise ValueError("Issue type '%s' is not supported." % value)
+        return value
+
+    @property
+    def cleaned_body(self) -> str:
+        pattern = r"<!--[\s\S]*?-->"
+        return re.sub(pattern, "", self.body)
+
+    @property
+    def color(self) -> Color:
+        """Get the color for the embed based on the issue type."""
+        for t in TYPES:
+            if t["name"] == self.type:
+                return t["color"]
+        return Color.from_str("#000000")  # Default to black if no match found
+
+    @property
+    def emoji(self) -> PartialEmoji | Emoji:
+        """
+        Return the emoji for the issue based on its type.
+        This is used for Discord embeds.
+        """
+        name = ""
+        for t in TYPES:
+            if t["name"] == self.type:
+                name: str = t["name"]
+        emoji_name = convert_name(name)
+        for emoji in self.repository.cog.application_emojis:
+            if emoji.name == emoji_name:
+                return emoji
+        return PartialEmoji.from_str("❓")
+
+    @property
+    def footer_text(self) -> str:
+        return f"{self.repository.owner}/{self.repository.name} • {'Merged' if self.merge_date else 'Created'}"
+
+    @property
+    def markdown_link(self) -> str:
+        return f"[{self.pretty_title}]({self.link})"
+
+    @property
+    def markdown_milestone_link(self) -> str:
+        if not self.milestone:
+            raise ValueError("Issue does not have a milestone.")
+        if self.milestone_url:
+            return f"[{self.milestone}]({self.milestone_url})"
+        return self.milestone
+
+    @property
+    def prefixed_number(self) -> str:
+        if self.repository.provider.service == "gitlab" and "pull_request" in self.type:
+            return f"!{self.number}"
+        return f"#{self.number}"
+
+    @property
+    def pretty_title(self) -> str:
+        """Return the title with the some extra metadata."""
+        return f"{str(self.emoji)} {self.title} ({self.prefixed_number})"
+
+    @property
+    def timestamp(self) -> datetime:
+        return self.merge_date if self.merge_date else self.creation_date
+
+    @property
+    def unix_timestamp(self) -> int:
+        return int(self.timestamp.timestamp())
+
+    async def send(self, ctx: commands.Context | Message, reply: bool = False, short: bool = False, **kwargs: Any) -> Message:
+        """Send an embed for this Issue.
+
+        Args:
+            ctx (commands.Context | discord.Message): The context to send the embed in.
+            reply (bool): Whether to reply to the message. Defaults to `False`.
+            short (bool): Whether to send a short embed. Defaults to `False`.
+            **kwargs (Any): Additional keyword arguments to pass to `discord.Messageable.send`.
+        """
+        if reply is True:
+            msg = await ctx.reply(embed=self.short_embed() if short else self.embed(), view=_IssueView(self), mention_author=False, **kwargs)
+        else:
+            msg = await ctx.channel.send(embed=self.short_embed() if short else self.embed(), view=_IssueView(self), **kwargs)
+        self._message = msg
+        return msg
+
+    def embed(self) -> Embed:
+        """Create an embed for this Issue."""
+        embed = self.short_embed()
+        body = self.cleaned_body
+        if len(body) > 4096:
+            body = body[:4093] + "..."
+        embed.description = body or "No description provided."
+
+        if len(self.labels) > 0:
+            formatted_labels: list[str] = []
+            for label in self.labels:
+                formatted_labels.extend((f"* {label}",))
+            embed.add_field(name=f"Labels [{len(self.labels)}]", value="\n".join(formatted_labels), inline=True)
+
+        if self.milestone:
+            embed.add_field(name="Milestone", value=self.markdown_milestone_link, inline=True)
+
+        return embed
+
+    def short_embed(self) -> Embed:
+        """Create a short embed for this Issue."""
+        embed = Embed(
+            url=self.link,
+            title=self.pretty_title,
+            color=self.color,
+        )
+
+        embed.set_author(
+            name=self.author,
+            url=self.author_url,
+            icon_url=self.author_avatar,
+        )
+
+        embed.set_footer(text=self.footer_text, icon_url=self.repository.provider.favicon_url)
+        embed.timestamp = self.timestamp
+        return embed
+
+
+class _IssueView(ui.View):
+    def __init__(self, issue: Issue, timeout: int = 240) -> None:
+        super().__init__(timeout=timeout)
+        self.issue = issue
+        self.timeout = timeout
+
+    async def on_timeout(self) -> None:
+        if self.issue._message is not None:  # noqa: SLF001
+            try:
+                await self.issue._message.edit(view=None)  # noqa: SLF001
+            except NotFound:
+                pass
+
+    @ui.button(emoji="🗑️", style=ButtonStyle.gray)
+    async def delete_message(self, interaction: Interaction, button: ui.Button) -> None:
+        await interaction.response.defer()
+        if interaction.message is not None:
+            try:
+                await interaction.message.delete()
+            except NotFound:
+                pass
+
+    @ui.button(label="Switch View", style=ButtonStyle.primary)
+    async def switch_message_embed(self, interaction: Interaction, button: ui.Button) -> None:
+        await interaction.response.defer()
+        if interaction.message is not None:
+            self.issue._has_short_embed = not self.issue._has_short_embed  # noqa: SLF001
+            try:
+                await interaction.message.edit(embed=self.issue.short_embed() if self.issue._has_short_embed else self.issue.embed())  # noqa: SLF001
+            except NotFound:
+                pass

issuecards/models/provider.py

@@ -0,0 +1,140 @@
+from typing import Any
+
+from discord import Guild
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from ..config import config
+
+SUPPORTED_PROVIDER_SERVICES = ["github", "gitlab", "forgejo"]
+
+
+class UnsupportedServiceError(Exception):
+    """Custom exception for unsupported provider services."""
+
+    pass
+
+
+class Provider(BaseModel):
+    """Model for a provider configuration.
+
+    Attributes:
+        id (str): The ID of the provider. This should usually be the same as the URl, just without the scheme (i.e. https://).
+        url (str): The URL of the provider.
+        service (str): The service type of the provider (e.g., `github`, `gitlab`, `forgejo`). Must be one of the supported services.
+        token (str): An optional API token for the provider. If not provided, unauthenticated requests will be used.
+        guild (Guild | None): The Discord guild associated with the provider. If `None`, the provider is considered a global provider.
+
+    Properties:
+        api_url (str): The API URL for the provider. This is typically the base URL with an API path appended.
+        favicon_url (str): The URL to the provider's favicon. This is typically the base URL with a favicon path appended.
+
+    Methods:
+        to_config: Save the provider to Red's configuration. Saves to guilds if the `guild` class attribute is not `None`.
+
+    Class Methods:
+        from_config: Create a Provider instance from the Red configuration. Checks both global and guild providers, prioritizing guild providers.
+        fetch_all: Fetch all providers from the Red configuration. Checks both global and guild providers
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    id: str
+    url: str
+    service: str
+    token: str | None = None
+    guild: Guild | None = None
+
+    @field_validator("service")
+    @classmethod
+    def _validate_provider(cls, value: Any) -> Any:
+        if value not in SUPPORTED_PROVIDER_SERVICES:
+            raise UnsupportedServiceError("Provider service '%s' is not supported." % value)
+        return value
+
+    @property
+    def api_url(self) -> str:
+        """Return the API URL for the provider. This is typically the base URL with an API path appended."""
+        match self.service:
+            case "github":
+                if self.url == "https://github.com":
+                    return "https://api.github.com"
+                return self.url.rstrip("/") + "/api/v3"
+            case "gitlab":
+                return self.url.rstrip("/") + "/api/v4"
+            case "forgejo":
+                return self.url.rstrip("/") + "/api/v1"
+            case _:
+                raise UnsupportedServiceError("Unsupported provider service:' '%s'" % self.service)
+
+    @property
+    def graphql_url(self) -> str:
+        """Return the GraphQL URL for the provider. This is typically the base URL with a GraphQL path appended."""
+        match self.service:
+            case "github":
+                if self.url == "https://github.com":
+                    return "https://api.github.com/graphql"
+                return self.url.rstrip("/") + "/api/graphql"
+            case "gitlab":
+                return self.url.rstrip("/") + "/api/graphql"
+            case "forgejo":
+                raise ValueError("Forgejo does not support GraphQL.")
+            case _:
+                raise UnsupportedServiceError("Unsupported provider service:' '%s'" % self.service)
+
+    @property
+    def favicon_url(self) -> str:
+        """Return the URL to the provider's favicon. This is typically the base URL with a favicon path appended."""
+        if self.service == "github":
+            # GitHub's favicon is *actually* an ico, and Discord can't embed those
+            return self.url.rstrip("/") + "/apple-touch-icon.png"
+        return self.url.rstrip("/") + "/favicon.ico"
+
+    async def to_config(self) -> None:
+        """Save the provider to Red's configuration. Saves to guilds if the `guild` class attribute is not `None`."""
+        if self.guild:
+            providers = await config.guild(self.guild).providers()
+        else:
+            providers = await config.global_providers()
+
+        for provider in providers:
+            if provider["url"] == self.url:
+                provider["token"] = self.token
+
+        if not any(provider["url"] == self.url for provider in providers):
+            providers.append(self.model_dump(mode="json", exclude={"guild"}))
+
+        if self.guild:
+            await config.guild(self.guild).providers.set(providers)
+        else:
+            await config.global_providers.set(providers)
+
+    @classmethod
+    async def from_config(cls, provider_id: str, guild: Guild | None = None) -> "Provider":
+        """Create a Provider instance from the Red configuration. Checks both global and guild providers, prioritizing guild providers."""
+        if guild:
+            guild_providers = await config.guild(guild).providers()
+            for provider in guild_providers:
+                if provider["id"] == provider_id:
+                    return cls(guild=guild, **provider)
+
+        providers = await config.global_providers()
+        for provider in providers:
+            if provider["id"] == provider_id:
+                return cls(guild=None, **provider)
+        raise ValueError("No provider found for ID: %s" % provider_id)
+
+    @classmethod
+    async def fetch_all(cls, guild: Guild | None = None) -> tuple["Provider"]:
+        """Fetch all providers from the Red configuration. Checks both global and guild providers."""
+        providers_list = []
+
+        if guild:
+            guild_providers = await config.guild(guild).providers()
+            for provider in guild_providers:
+                providers_list.extend((cls(guild=guild, **provider),))
+
+        global_providers = await config.global_providers()
+        for provider in global_providers:
+            providers_list.extend((cls(guild=None, **provider),))
+
+        return tuple(providers_list)

issuecards/models/repository.py

@@ -0,0 +1,140 @@
+from sys import version as pyversion
+
+from discord import Guild
+from pydantic import BaseModel, ConfigDict
+from redbot import version_info
+from redbot.core.bot import commands
+
+from ..config import config
+from .provider import Provider
+
+
+class Repository(BaseModel):
+    """Model for a repository configuration.
+
+    Attributes:
+        cog (commands.Cog): The cog object that allows accessing a discord.py Bot object, along other things.
+        owner (str): The owner of the repository.
+        repository (str): The name of the repository.
+        prefix (str): Prefix used for determining which repository to retrieve an issue from when using the `#<issue-num>` syntax
+        provider (Provider): The provider configuration for the repository. This requires a provider to be registered at the given URL.
+        guild (Guild | None): The Discord guild associated with the repository. If None, the repository is considered a global repository.
+
+    Properties:
+        url (str): The URL for the repository.
+        user_agent (str): The user agent for API requests using this object.
+
+    Methods:
+        to_config: Save the repository to Red's configuration. Saves to guilds if the `guild` class attribute is set.
+        remove_config: Remove the repository from Red's configuration. Removes from guilds if the `guild` class attribute is set.
+
+    Class Methods:
+        from_config: Create a Repository instance from the Red configuration. Checks both global and guild repositories, prioritizing guild repositories.
+        from_prefix: Create a Repository instance from the Red configuration using the prefix. Checks both global and guild repositories, prioritizing guild repositories.
+        fetch_all: Fetch all repositories from the Red configuration. Returns a list of Repository instances.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    cog: commands.Cog
+    owner: str
+    name: str
+    prefix: str | None = None
+    provider: Provider
+    guild: Guild | None = None
+
+    @property
+    def url(self) -> str:
+        """Return the URL for the repository."""
+        return f"{self.provider.url.rstrip('/')}/{self.owner}/{self.name}"
+
+    @property
+    def user_agent(self) -> str:
+        """Return the user agent for API requests using this object."""
+        return f"Red-DiscordBot/{version_info} {self.cog.__cog_name__}/{self.cog.__version__} ({self.cog.__git__}) (Python {pyversion})"
+
+    async def to_config(self) -> None:
+        """Save the repository to Red's configuration. Saves to guilds if the `guild` class attribute is set."""
+        if self.guild:
+            repositories = await config.guild(self.guild).repositories()
+        else:
+            repositories = await config.global_repositories()
+
+        for repo in repositories:
+            if repo["owner"] == self.owner and repo["name"] == self.name:
+                repo["provider"] = self.provider.id
+
+        if not any(repo["owner"] == self.owner and repo["name"] == self.name for repo in repositories):
+            repositories.append({"owner": self.owner, "name": self.name, "prefix": self.prefix, "provider": self.provider.id})
+
+        if self.guild:
+            await config.guild(self.guild).repositories.set(repositories)
+        else:
+            await config.global_repositories.set(repositories)
+
+    async def remove_config(self) -> None:
+        """Remove the repository from Red's configuration. Removes from guilds if the `guild` class attribute is set."""
+        if self.guild:
+            repositories = await config.guild(self.guild).repositories()
+            repositories = [repo for repo in repositories if not (repo["provider"] == self.provider.id and repo["owner"] == self.owner and repo["name"] == self.name)]
+            await config.guild(self.guild).repositories.set(repositories)
+        else:
+            repositories = await config.global_repositories()
+            repositories = [repo for repo in repositories if not (repo["provider"] == self.provider.id and repo["owner"] == self.owner and repo["name"] == self.name)]
+            await config.global_repositories.set(repositories)
+
+    @classmethod
+    async def from_config(cls, cog: commands.Cog, provider_id: str, owner: str, repository: str, guild: Guild | None = None) -> "Repository":
+        """Create a Repository instance from the Red configuration. Checks both global and guild repositories, prioritizing guild repositories."""
+        if guild:
+            guild_repositories = await config.guild(guild).repositories()
+            for repo in guild_repositories:
+                if repo["provider"] == provider_id and repo["owner"] == owner and repo["name"] == repository:
+                    try:
+                        provider = await Provider.from_config(repo["provider"], guild=guild)
+                    except ValueError:
+                        pass
+                    return cls(cog=cog, guild=guild, owner=owner, name=repository, prefix=repo["prefix"], provider=provider)
+
+        repositories = await config.global_repositories()
+        for repo in repositories:
+            if repo["provider"] == provider_id and repo["owner"] == owner and repo["name"] == repository:
+                try:
+                    provider = await Provider.from_config(repo["provider"])
+                except ValueError as e:
+                    raise ValueError("Failed to create provider from config: '%s'" % str(e)) from e
+                return cls(cog=cog, guild=None, owner=owner, name=repository, prefix=repo["prefix"], provider=provider)
+
+        raise ValueError("No repository found for owner: '%s' and repository: '%s'" % (owner, repository))
+
+    @classmethod
+    async def from_prefix(cls, cog: commands.Cog, prefix: str, guild: Guild | None = None) -> "Repository":
+        """Create a Repository instance from the Red configuration using the prefix. Checks both global and guild repositories, prioritizing guild repositories."""
+        repositories = await cls.fetch_all(cog, guild)
+        for repo in repositories:
+            if repo.prefix is not None and repo.prefix == prefix:
+                return repo
+        raise ValueError("No repository found for prefix: '%s'" % prefix)
+
+    @classmethod
+    async def fetch_all(cls, cog: commands.Cog, guild: Guild | None = None) -> tuple["Repository"]:
+        """Fetch all repositories from the Red configuration. Returns a list of Repository instances."""
+        repositories_list = []
+        if guild:
+            guild_repositories = await config.guild(guild).repositories()
+            for repo in guild_repositories:
+                try:
+                    provider = await Provider.from_config(repo["provider"], guild=guild)
+                except ValueError:
+                    continue
+                repositories_list.append(cls(cog=cog, guild=guild, owner=repo["owner"], name=repo["name"], prefix=repo["prefix"], provider=provider))
+
+        global_repositories = await config.global_repositories()
+        for repo in global_repositories:
+            try:
+                provider = await Provider.from_config(repo["provider"])
+            except ValueError:
+                continue
+            repositories_list.append(cls(cog=cog, guild=None, owner=repo["owner"], name=repo["name"], prefix=repo["prefix"], provider=provider))
+
+        return tuple(repositories_list)

issuecards/view.py

@@ -0,0 +1,22 @@
+from discord import Interaction, Message, NotFound, ui
+from redbot.core import commands
+from redbot.core.utils.mod import is_admin_or_superior
+
+
+class ProviderAddView(ui.View):
+    def __init__(self, ctx: commands.Context, message: Message, timeout: int | None = None) -> None:
+        super().__init__(timeout=timeout)
+        self.ctx = ctx
+        self.message = message
+
+        async def on_timeout() -> None:
+            try:
+                await self.message.edit(view=None)
+            except NotFound:
+                pass
+
+        async def interaction_check(self, interaction: Interaction) -> bool:
+            if await interaction.client.is_owner(interaction.user) or (interaction.guild and await is_admin_or_superior(self.ctx.bot, interaction.author)):
+                return True
+            await interaction.response.send_message("This button is only for bot owners or server administrators.", ephemeral=True)
+            return False

pyproject.toml

@@ -7,33 +7,35 @@ license = { file = "LICENSE" }
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-  "aiosqlite==0.21.0",
+  "aiosqlite>=0.20.0",
-  "beautifulsoup4==4.13.3",
+  "beautifulsoup4>=4.12.3",
-  "colorthief==0.2.1",
+  "cairosvg>=2.7.1",
-  "markdownify==1.1.0",
+  "colorthief>=0.2.1",
-  "numpy==2.2.4",
+  "markdownify>=0.14.1",
-  "phx-class-registry==5.1.1",
+  "numpy>=2.2.2",
-  "pillow==10.4.0",
+  "phx-class-registry>=5.1.1",
-  "pip==25.0.1",
+  "pillow>=10.4.0",
+  "pip>=25.0",
   "py-dactyl",
-  "pydantic==2.11.1",
+  "pydantic>=2.10.6",
-  "red-discordbot==3.5.18",
+  "pyocticons",
-  "watchdog==6.0.0",
+  "red-discordbot>=3.5.17",
-  "websockets==15.0.1",
+  "watchdog>=6.0.0",
+  "websockets>=14.2",
 ]
 
 [dependency-groups]
 documentation = [
-  "mkdocs==1.6.1",
+  "mkdocs>=1.6.1",
-  "mkdocs-git-authors-plugin==0.9.4",
+  "mkdocs-git-authors-plugin>=0.9.2",
-  "mkdocs-git-revision-date-localized-plugin==1.4.5",
+  "mkdocs-git-revision-date-localized-plugin>=1.3.0",
-  "mkdocs-material[imaging]==9.6.10",
+  "mkdocs-material[imaging]>=9.5.50",
-  "mkdocs-redirects==1.2.2",
+  "mkdocs-redirects>=1.2.2",
-  "mkdocstrings[python]==0.29.0",
+  "mkdocstrings[python]>=0.27.0",
 ]
 
 [tool.uv]
-dev-dependencies = ["pylint==3.3.6", "ruff==0.11.2", "sqlite-web==0.6.4"]
+dev-dependencies = ["pylint>=3.3.3", "ruff>=0.9.3", "sqlite-web>=0.6.4"]
 
 [tool.uv.sources]
 py-dactyl = { git = "https://github.com/iamkubi/pydactyl", tag = "v2.0.5" }

uv.lock

@@ -1,5 +1,4 @@
 version = 1
-revision = 1
 requires-python = ">=3.11"
 resolution-markers = [
     "python_full_version >= '3.13'",
@@ -624,14 +623,14 @@ wheels = [
 
 [[package]]
 name = "griffe"
-version = "1.7.1"
+version = "1.7.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/30/1b/fe7a3a33a2fb7ad7807f71957e6108a50d93271ab718d9a56080415f66de/griffe-1.7.1.tar.gz", hash = "sha256:464730d0e95d0afd038e699a5f7276d7438d0712db0c489a17e761f70e011507", size = 394522 }
+sdist = { url = "https://files.pythonhosted.org/packages/cc/e1/7dded768fe1adf67879bcd86cf83476e7b19f13d95e6504b6c2b91092f8c/griffe-1.7.0.tar.gz", hash = "sha256:72e9c1593c7af92a387906293fc4a318c2e8e8aef501c64678c809794b4bdca4", size = 394351 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/1d/94/48e28b1c7402f750200e9e3ef4834c862ea85c64f426a231a6dc312f61a9/griffe-1.7.1-py3-none-any.whl", hash = "sha256:37a7f15233937d723ddc969fa4117fdd03988885c16938dc43bccdfe8fa4d02d", size = 129134 },
+    { url = "https://files.pythonhosted.org/packages/66/b3/6201c5dc97ed76398eb419d17fe18db6b4b3ffb2baa2bae91b4c65126096/griffe-1.7.0-py3-none-any.whl", hash = "sha256:6b44efc53a3f290d42c4da521f42235177b3bd107877dd55955318a37930c572", size = 129118 },
 ]
 
 [[package]]
@@ -875,7 +874,7 @@ wheels = [
 
 [[package]]
 name = "mkdocs-material"
-version = "9.6.10"
+version = "9.6.9"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "babel" },
@@ -890,9 +889,9 @@ dependencies = [
     { name = "pymdown-extensions" },
     { name = "requests" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/e6/fc/f42c09e3fe13d48193edf22a63484186b0be67a73fc006eab389bf47d66f/mkdocs_material-9.6.10.tar.gz", hash = "sha256:25a453c1f24f34fcf1f53680c03d2c1421b52ce5247f4468153c87a70cd5f1fc", size = 3951725 }
+sdist = { url = "https://files.pythonhosted.org/packages/11/cb/6dd3b6a7925429c0229738098ee874dbf7fa02db55558adb2c5bf86077b2/mkdocs_material-9.6.9.tar.gz", hash = "sha256:a4872139715a1f27b2aa3f3dc31a9794b7bbf36333c0ba4607cf04786c94f89c", size = 3948083 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e4/2f/e210215a3c2918739096ff7bf71a3cf32b7d8d1dfd5ceff8a82e2741dc16/mkdocs_material-9.6.10-py3-none-any.whl", hash = "sha256:36168548df4e2ddeb9a334ddae4ab9c388ccfea4dd50ffee657d22b93dcb1c3e", size = 8703722 },
+    { url = "https://files.pythonhosted.org/packages/db/7c/ea5a671b2ff5d0e3f3108a7f7d75b541d683e4969aaead2a8f3e59e0fc27/mkdocs_material-9.6.9-py3-none-any.whl", hash = "sha256:6e61b7fb623ce2aa4622056592b155a9eea56ff3487d0835075360be45a4c8d1", size = 8697935 },
 ]
 
 [package.optional-dependencies]
@@ -1299,7 +1298,7 @@ wheels = [
 
 [[package]]
 name = "pydantic"
-version = "2.11.1"
+version = "2.11.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "annotated-types" },
@@ -1307,9 +1306,9 @@ dependencies = [
     { name = "typing-extensions" },
     { name = "typing-inspection" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/93/a3/698b87a4d4d303d7c5f62ea5fbf7a79cab236ccfbd0a17847b7f77f8163e/pydantic-2.11.1.tar.gz", hash = "sha256:442557d2910e75c991c39f4b4ab18963d57b9b55122c8b2a9cd176d8c29ce968", size = 782817 }
+sdist = { url = "https://files.pythonhosted.org/packages/82/2a/4ba34614269b1e12a28b9fe54710983f5c3679f945797e86250c6269263f/pydantic-2.11.0.tar.gz", hash = "sha256:d6a287cd6037dee72f0597229256dfa246c4d61567a250e99f86b7b4626e2f41", size = 782184 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/cc/12/f9221a949f2419e2e23847303c002476c26fbcfd62dc7f3d25d0bec5ca99/pydantic-2.11.1-py3-none-any.whl", hash = "sha256:5b6c415eee9f8123a14d859be0c84363fec6b1feb6b688d6435801230b56e0b8", size = 442648 },
+    { url = "https://files.pythonhosted.org/packages/09/2c/3a0a1b022bb028e4cd455c69a17ceaad809bf6763c110d093efc0d8f67aa/pydantic-2.11.0-py3-none-any.whl", hash = "sha256:d52535bb7aba33c2af820eaefd866f3322daf39319d03374921cd17fbbdf28f9", size = 442591 },
 ]
 
 [[package]]
@@ -1417,6 +1416,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/eb/f5/b9e2a42aa8f9e34d52d66de87941ecd236570c7ed2e87775ed23bbe4e224/pymdown_extensions-10.14.3-py3-none-any.whl", hash = "sha256:05e0bee73d64b9c71a4ae17c72abc2f700e8bc8403755a00580b49a4e9f189e9", size = 264467 },
 ]
 
+[[package]]
+name = "pyocticons"
+version = "0.1.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/76/52/c50b54ca4c8d8ab3eee07a4323ac505e63c51b25c68a6a3c881cdcf3f886/pyocticons-0.1.1.tar.gz", hash = "sha256:05849a17c6c73cb4e90315411d26645954f0a9a56b9435b0d9f4601b16f6df2f", size = 95976 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/6b/d5/26ecd9a905813a9b7c5565c176f3fcf2e56dfea7652bbf823b25bba9c0a4/pyocticons-0.1.1-py3-none-any.whl", hash = "sha256:b364549b2b8ccbe1f8ee61a97f39d5e3a3d2e9d434781586a322f2259fcfbee8", size = 98759 },
+]
+
 [[package]]
 name = "python-dateutil"
 version = "2.9.0.post0"
@@ -1679,6 +1687,7 @@ source = { virtual = "." }
 dependencies = [
     { name = "aiosqlite" },
     { name = "beautifulsoup4" },
+    { name = "cairosvg" },
     { name = "colorthief" },
     { name = "markdownify" },
     { name = "numpy" },
@@ -1687,6 +1696,7 @@ dependencies = [
     { name = "pip" },
     { name = "py-dactyl" },
     { name = "pydantic" },
+    { name = "pyocticons" },
     { name = "red-discordbot" },
     { name = "watchdog" },
     { name = "websockets" },
@@ -1709,34 +1719,36 @@ documentation = [
 
 [package.metadata]
 requires-dist = [
-    { name = "aiosqlite", specifier = "==0.21.0" },
+    { name = "aiosqlite", specifier = ">=0.20.0" },
-    { name = "beautifulsoup4", specifier = "==4.13.3" },
+    { name = "beautifulsoup4", specifier = ">=4.12.3" },
-    { name = "colorthief", specifier = "==0.2.1" },
+    { name = "cairosvg", specifier = ">=2.7.1" },
-    { name = "markdownify", specifier = "==1.1.0" },
+    { name = "colorthief", specifier = ">=0.2.1" },
-    { name = "numpy", specifier = "==2.2.4" },
+    { name = "markdownify", specifier = ">=0.14.1" },
-    { name = "phx-class-registry", specifier = "==5.1.1" },
+    { name = "numpy", specifier = ">=2.2.2" },
-    { name = "pillow", specifier = "==10.4.0" },
+    { name = "phx-class-registry", specifier = ">=5.1.1" },
-    { name = "pip", specifier = "==25.0.1" },
+    { name = "pillow", specifier = ">=10.4.0" },
+    { name = "pip", specifier = ">=25.0" },
     { name = "py-dactyl", git = "https://github.com/iamkubi/pydactyl?tag=v2.0.5" },
-    { name = "pydantic", specifier = "==2.11.1" },
+    { name = "pydantic", specifier = ">=2.10.6" },
-    { name = "red-discordbot", specifier = "==3.5.18" },
+    { name = "pyocticons" },
-    { name = "watchdog", specifier = "==6.0.0" },
+    { name = "red-discordbot", specifier = ">=3.5.17" },
-    { name = "websockets", specifier = "==15.0.1" },
+    { name = "watchdog", specifier = ">=6.0.0" },
+    { name = "websockets", specifier = ">=14.2" },
 ]
 
 [package.metadata.requires-dev]
 dev = [
-    { name = "pylint", specifier = "==3.3.6" },
+    { name = "pylint", specifier = ">=3.3.3" },
-    { name = "ruff", specifier = "==0.11.2" },
+    { name = "ruff", specifier = ">=0.9.3" },
-    { name = "sqlite-web", specifier = "==0.6.4" },
+    { name = "sqlite-web", specifier = ">=0.6.4" },
 ]
 documentation = [
-    { name = "mkdocs", specifier = "==1.6.1" },
+    { name = "mkdocs", specifier = ">=1.6.1" },
-    { name = "mkdocs-git-authors-plugin", specifier = "==0.9.4" },
+    { name = "mkdocs-git-authors-plugin", specifier = ">=0.9.2" },
-    { name = "mkdocs-git-revision-date-localized-plugin", specifier = "==1.4.5" },
+    { name = "mkdocs-git-revision-date-localized-plugin", specifier = ">=1.3.0" },
-    { name = "mkdocs-material", extras = ["imaging"], specifier = "==9.6.10" },
+    { name = "mkdocs-material", extras = ["imaging"], specifier = ">=9.5.50" },
-    { name = "mkdocs-redirects", specifier = "==1.2.2" },
+    { name = "mkdocs-redirects", specifier = ">=1.2.2" },
-    { name = "mkdocstrings", extras = ["python"], specifier = "==0.29.0" },
+    { name = "mkdocstrings", extras = ["python"], specifier = ">=0.27.0" },
 ]
 
 [[package]]