feat: add download-source link to notifications + markdown link formatting

- Add _format_link() helper: [label](url) for markdown, label: url for text
- Split Apprise URLs into two instances (markdown-capable vs text-only)
- Auto-upgrade ntfy URLs with ?format=markdown
- Add download-source link (FitGirl/FreeGOG) between Metacritic and YouTube in notification body
- Thread source_name/source_url from pipeline matching to notification call
- Extract _append_optional_fields helper (CRAP 9.08→6.00)
- 100% test coverage on notifications.py (47 tests)

Closes: download-source-link-notification

Author: binhex

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gamarr"
-version = "1.1.6"
+version = "1.1.7"
 description = "Metadata game downloader - torrent metadata harvester"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -100,4 +100,4 @@ dev = [
     "pre-commit",
     "mypy",
     "ruff"
-]
+]

src/gamarr/notifications.py

@@ -7,6 +7,8 @@
 
 from loguru import logger
 
+_MARKDOWN_SCHEMES = frozenset({"ntfy", "ntfys", "discord", "slack", "tgram", "tg", "matrix", "matrixs"})
+
 
 class Notifier:
     """Sends notifications for gamarr events via Apprise."""
@@ -24,16 +26,28 @@ def __init__(
         self._on_failure = on_failure
         self._on_error = on_error
         self._on_scrape_failure = on_scrape_failure
-        self._apprise = self._init_apprise()
 
-    def _init_apprise(self) -> Any:
-        if not self._urls:
+        # Split URLs into markdown-capable and text-only groups
+        self._md_urls: list[str] = []
+        self._text_urls: list[str] = []
+        for url in self._urls:
+            if Notifier._is_markdown_service(url):
+                self._md_urls.append(Notifier._maybe_upgrade_ntfy(url))
+            else:
+                self._text_urls.append(url)
+
+        self._apprise_md = self._init_apprise(self._md_urls)
+        self._apprise_text = self._init_apprise(self._text_urls)
+
+    @staticmethod
+    def _init_apprise(urls: list[str]) -> Any:
+        if not urls:
             return None
         try:
             import apprise
 
             apobj = apprise.Apprise()
-            for url in self._urls:
+            for url in urls:
                 apobj.add(url)
             return apobj
         except Exception as exc:
@@ -61,6 +75,45 @@ def _youtube_search_url(title: str) -> str:
         query = urllib.parse.quote_plus(f"{title} review")
         return f"https://www.youtube.com/results?search_query={query}"
 
+    @staticmethod
+    def _is_markdown_service(url: str) -> bool:
+        """Return True if *url* uses a scheme that supports markdown formatting."""
+        try:
+            scheme = url.split("://", 1)[0].lower()
+        except (ValueError, AttributeError):
+            return False
+        return scheme in _MARKDOWN_SCHEMES
+
+    @staticmethod
+    def _maybe_upgrade_ntfy(url: str) -> str:
+        """Append ``?format=markdown`` to ntfy URLs that don't already have it."""
+        try:
+            scheme = url.split("://", 1)[0].lower()
+        except (ValueError, AttributeError):
+            return url
+        if scheme not in ("ntfy", "ntfys"):
+            return url
+        if "format=markdown" in url:
+            return url
+        sep = "&" if "?" in url else "?"
+        return f"{url}{sep}format=markdown"
+
+    @staticmethod
+    def _format_link(label: str, url: str, *, use_markdown: bool) -> str:
+        """Format a clickable link line.
+
+        Args:
+            label: Display text for the link (e.g. ``"Metacritic"``).
+            url: The full URL.
+            use_markdown: If True, produce ``[label](url)``; otherwise ``label: url``.
+
+        Returns:
+            A single-line string suitable for the notification body.
+        """
+        if use_markdown:
+            return f"[{label}]({url})"
+        return f"{label}: {url}"
+
     def send_download_notification(
         self,
         title: str,
@@ -74,10 +127,14 @@ def send_download_notification(
         genres: list[str] | None = None,
         must_play: bool | None = None,
         release_date: str | None = None,
+        source_name: str | None = None,
+        source_url: str | None = None,
     ) -> None:
-        if not self._on_download or not self._apprise:
+        if not self._on_download:
+            return
+        if not self._apprise_md and not self._apprise_text:
             return
-        body = self._format_download_body(
+        text_body = self._format_download_body(
             add_paused=add_paused,
             metascore=metascore,
             metascore_reviews=metascore_reviews,
@@ -89,8 +146,45 @@ def send_download_notification(
             slug=slug,
             title=title,
             platform=platform,
+            source_name=source_name,
+            source_url=source_url,
+            use_markdown=False,
         )
-        self._send(f"gamarr - {title} ({platform})", body)
+        md_body = None
+        if self._apprise_md:
+            md_body = self._format_download_body(
+                add_paused=add_paused,
+                metascore=metascore,
+                metascore_reviews=metascore_reviews,
+                user_score=user_score,
+                user_reviews=user_reviews,
+                must_play=must_play,
+                genres=genres,
+                release_date=release_date,
+                slug=slug,
+                title=title,
+                platform=platform,
+                source_name=source_name,
+                source_url=source_url,
+                use_markdown=True,
+            )
+        self._send(f"gamarr - {title} ({platform})", text_body, body_markdown=md_body)
+
+    @staticmethod
+    def _append_optional_fields(
+        parts: list[str],
+        *,
+        must_play: bool | None,
+        genres: list[str] | None,
+        release_date: str | None,
+    ) -> None:
+        """Append optional metadata fields to the body parts list."""
+        if must_play is not None:
+            parts.append(f"Must Play: {'Yes' if must_play else 'No'}")
+        if genres:
+            parts.append(f"Genre: {', '.join(genres)}")
+        if release_date:
+            parts.append(f"Release: {release_date}")
 
     @staticmethod
     def _format_download_body(
@@ -106,33 +200,39 @@ def _format_download_body(
         slug: str,
         title: str,
         platform: str,
+        source_name: str | None = None,
+        source_url: str | None = None,
+        use_markdown: bool = False,
     ) -> str:
         """Build the notification body string for a game download."""
+        link = Notifier._format_link
+        mk = use_markdown
         parts = [f"Status: {'Paused' if add_paused else 'Downloading'}"]
         parts.extend(
             [
                 Notifier._format_score_line("Critic Score", metascore, metascore_reviews),
                 Notifier._format_score_line("User Score", user_score, user_reviews),
             ]
         )
-        if must_play is not None:
-            parts.append(f"Must Play: {'Yes' if must_play else 'No'}")
-        if genres:
-            parts.append(f"Genre: {', '.join(genres)}")
-        if release_date:
-            parts.append(f"Release: {release_date}")
-        parts.append(f"Metacritic: https://www.metacritic.com/game/{slug or 'unknown'}/")
-        parts.append(f"YouTube: {Notifier._youtube_search_url(title)}")
+        Notifier._append_optional_fields(parts, must_play=must_play, genres=genres, release_date=release_date)
+        parts.append(link("Metacritic", f"https://www.metacritic.com/game/{slug or 'unknown'}", use_markdown=mk))
+        if source_name and source_url:
+            parts.append(link(source_name.title(), source_url, use_markdown=mk))
+        parts.append(link("YouTube", Notifier._youtube_search_url(title), use_markdown=mk))
         return "\n".join(parts)
 
     def send_failure_notification(self, title: str, reason: str) -> None:
-        if not self._on_failure or not self._apprise:
+        if not self._on_failure:
+            return
+        if not self._apprise_md and not self._apprise_text:
             return
         body = f"gamarr: {title} failed checks\nReason: {reason}"
         self._send("gamarr - Failed", body)
 
     def send_error_notification(self, error_message: str) -> None:
-        if not self._on_error or not self._apprise:
+        if not self._on_error:
+            return
+        if not self._apprise_md and not self._apprise_text:
             return
         body = f"gamarr pipeline error:\n{error_message}"
         self._send("gamarr - Error", body)
@@ -145,15 +245,29 @@ def send_scrape_notification(self, message: str) -> None:
         Args:
             message: Description of the scraping issue to include in the body.
         """
-        if not self._on_scrape_failure or not self._apprise:
+        if not self._on_scrape_failure:
+            return
+        if not self._apprise_md and not self._apprise_text:
             return
         body = f"{message}\n\nThis may indicate a Metacritic site change or network issue."
         self._send("gamarr - Scraping Issue", body)
 
-    def _send(self, title: str, body: str) -> None:
-        if not self._apprise:
-            return
-        try:
-            self._apprise.notify(title=title, body=body)
-        except Exception as exc:
-            logger.warning("Failed to send notification '{}': {}", title, exc)
+    def _send(self, title: str, body: str, *, body_markdown: str | None = None) -> None:
+        """Send notification to both markdown and text instances.
+
+        Args:
+            title: Notification title (shared across all instances).
+            body: Plain-text body for the text instance (label: url format).
+            body_markdown: Markdown body for the markdown instance
+                ([label](url) format). If None, markdown instance is skipped.
+        """
+        if self._apprise_md and body_markdown is not None:
+            try:
+                self._apprise_md.notify(title=title, body=body_markdown)
+            except Exception as exc:
+                logger.warning("Failed to send markdown notification '{}': {}", title, exc)
+        if self._apprise_text:
+            try:
+                self._apprise_text.notify(title=title, body=body)
+            except Exception as exc:
+                logger.warning("Failed to send text notification '{}': {}", title, exc)

src/gamarr/pipeline.py

@@ -1437,6 +1437,7 @@ def _deliver_with_jit_verify(
     magnet_fetcher: Callable[[str], str | None],
     notifier: Any,
     best: dict[str, Any],
+    source_name: str = "fitgirl",
 ) -> dict[str, Any] | None:
     """Verify scores just-in-time, then deliver the match.
 
@@ -1483,6 +1484,7 @@ def _deliver_with_jit_verify(
         game_genres=game_genres,
         game_must_play=game_must_play,
         game_release_date=game_release_date,
+        source_name=source_name,
     )
 
 
@@ -1592,6 +1594,7 @@ def _deliver_match(
     game_genres: list[str] | None = None,
     game_must_play: bool | None = None,
     game_release_date: str | None = None,
+    source_name: str = "fitgirl",
 ) -> dict[str, Any]:
     """Deliver a matched pending game to qBittorrent and emit notifications.
 
@@ -1694,6 +1697,8 @@ def _deliver_match(
         must_play=game_must_play,
         release_date=game_release_date,
         add_paused=qbt.add_paused,
+        source_name=source_name,
+        source_url=best["url"],
     )
     return record_result
 
@@ -1820,6 +1825,7 @@ def _process_single_pending_match(
             magnet_fetcher=magnet_fetcher,
             notifier=notifier,
             best=best,
+            source_name=source_name,
         )
         if result_dict is not None:
             return result_dict