feat: add logfire spans and structured error handling to notifications

- add NotificationResult dataclass with success, error, error_type fields
- categorize errors: dm_blocked, network, auth, unknown
- add logfire spans to _send_dm_to_did and send_copyright_notification
- log warnings with structured data when notifications fail
- return tuple of results so caller knows exactly what happened

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

backend/src/backend/_internal/moderation.py

···
                 .where(Track.id == track_id)
             )
             if track and track.artist:
-                notified = await notification_service.send_copyright_notification(
+                (
+                    artist_result,
+                    admin_result,
+                ) = await notification_service.send_copyright_notification(
                     track_id=track_id,
                     track_title=track.title,
                     artist_did=track.artist_did,
···
                     highest_score=scan.highest_score,
                     matches=scan.matches,
                 )
-                if notified:
+                # mark as notified if at least one succeeded
+                if (artist_result and artist_result.success) or (
+                    admin_result and admin_result.success
+                ):
                     scan.notified_at = datetime.now(UTC)
                     await db.commit()
 

backend/src/backend/_internal/notifications.py

···
 """notification service for relay events."""
 
 import logging
+from dataclasses import dataclass
 
+import logfire
 from atproto import AsyncClient, models
 
 from backend.config import settings
 from backend.models import Track
 
 logger = logging.getLogger(__name__)
+
+
+@dataclass
+class NotificationResult:
+    """result of a notification attempt."""
+
+    success: bool
+    recipient_did: str
+    error: str | None = None
+    error_type: str | None = None  # "dm_blocked", "network", "auth", "unknown"
 
 
 class NotificationService:
···
             self.dm_client = None
             self.recipient_did = None
 
-    async def _send_dm_to_did(self, recipient_did: str, message_text: str) -> bool:
+    async def _send_dm_to_did(
+        self, recipient_did: str, message_text: str
+    ) -> NotificationResult:
         """send a DM to a specific DID.
 
-        returns True if sent successfully, False otherwise.
+        returns NotificationResult with success status and error details.
         """
         if not self.dm_client:
-            logger.warning("dm client not authenticated, skipping notification")
-            return False
+            return NotificationResult(
+                success=False,
+                recipient_did=recipient_did,
+                error="dm client not authenticated",
+                error_type="auth",
+            )
 
-        try:
-            dm = self.dm_client.chat.bsky.convo
+        with logfire.span(
+            "send_dm",
+            recipient_did=recipient_did,
+            message_length=len(message_text),
+        ) as span:
+            try:
+                dm = self.dm_client.chat.bsky.convo
 
-            convo_response = await dm.get_convo_for_members(
-                models.ChatBskyConvoGetConvoForMembers.Params(members=[recipient_did])
-            )
+                convo_response = await dm.get_convo_for_members(
+                    models.ChatBskyConvoGetConvoForMembers.Params(
+                        members=[recipient_did]
+                    )
+                )
 
-            if not convo_response.convo or not convo_response.convo.id:
-                raise ValueError("failed to get conversation ID")
+                if not convo_response.convo or not convo_response.convo.id:
+                    span.set_attribute("error_type", "no_convo")
+                    return NotificationResult(
+                        success=False,
+                        recipient_did=recipient_did,
+                        error="failed to get conversation ID - user may have DMs disabled",
+                        error_type="dm_blocked",
+                    )
 
-            await dm.send_message(
-                models.ChatBskyConvoSendMessage.Data(
-                    convo_id=convo_response.convo.id,
-                    message=models.ChatBskyConvoDefs.MessageInput(text=message_text),
+                await dm.send_message(
+                    models.ChatBskyConvoSendMessage.Data(
+                        convo_id=convo_response.convo.id,
+                        message=models.ChatBskyConvoDefs.MessageInput(
+                            text=message_text
+                        ),
+                    )
                 )
-            )
-            return True
+
+                span.set_attribute("success", True)
+                return NotificationResult(success=True, recipient_did=recipient_did)
 
-        except Exception:
-            logger.exception(f"error sending DM to {recipient_did}")
-            return False
+            except Exception as e:
+                error_str = str(e)
+                error_type = "unknown"
+
+                # try to categorize the error
+                if "blocked" in error_str.lower() or "not allowed" in error_str.lower():
+                    error_type = "dm_blocked"
+                elif "timeout" in error_str.lower() or "connect" in error_str.lower():
+                    error_type = "network"
+                elif "auth" in error_str.lower() or "401" in error_str:
+                    error_type = "auth"
+
+                span.set_attribute("error_type", error_type)
+                span.set_attribute("error", error_str)
+                logger.exception(f"error sending DM to {recipient_did}")
+
+                return NotificationResult(
+                    success=False,
+                    recipient_did=recipient_did,
+                    error=error_str,
+                    error_type=error_type,
+                )
 
     async def send_copyright_notification(
         self,
···
         artist_handle: str,
         highest_score: int,
         matches: list[dict],
-    ) -> bool:
+    ) -> tuple[NotificationResult | None, NotificationResult | None]:
         """send notification about a copyright flag to both artist and admin.
 
-        returns True if at least one notification was sent successfully.
+        returns (artist_result, admin_result) tuple with details of each attempt.
         """
-        if not self.dm_client:
-            logger.warning("dm client not authenticated, skipping notification")
-            return False
+        with logfire.span(
+            "copyright_notification",
+            track_id=track_id,
+            track_title=track_title,
+            artist_did=artist_did,
+            artist_handle=artist_handle,
+            highest_score=highest_score,
+            match_count=len(matches),
+        ) as span:
+            if not self.dm_client:
+                logfire.warn("dm client not authenticated, skipping notification")
+                return None, None
+
+            # format match info
+            match_count = len(matches)
+            primary_match = None
+            if matches:
+                m = matches[0]
+                primary_match = (
+                    f"{m.get('title', 'Unknown')} by {m.get('artist', 'Unknown')}"
+                )
+
+            # build track URL if available
+            track_url = None
+            frontend_url = settings.frontend.url
+            if frontend_url and "localhost" not in frontend_url:
+                track_url = f"{frontend_url}/track/{track_id}"
 
-        # format match info
-        match_count = len(matches)
-        primary_match = None
-        if matches:
-            m = matches[0]
-            primary_match = (
-                f"{m.get('title', 'Unknown')} by {m.get('artist', 'Unknown')}"
+            # message for the artist (uploader)
+            artist_message = (
+                f"⚠️ copyright notice for your track on {settings.app.name}\n\n"
+                f"track: '{track_title}'\n"
+                f"match confidence: {highest_score}%\n"
+            )
+            if primary_match:
+                artist_message += f"potential match: {primary_match}\n"
+            artist_message += (
+                "\nif you believe this is an error, please reply to this message. "
+                "otherwise, the track may be removed after review."
             )
 
-        # build track URL if available
-        track_url = None
-        frontend_url = settings.frontend.url
-        if frontend_url and "localhost" not in frontend_url:
-            track_url = f"{frontend_url}/track/{track_id}"
+            # message for admin
+            admin_message = (
+                f"🚨 copyright flag on {settings.app.name}\n\n"
+                f"track: '{track_title}'\n"
+                f"artist: @{artist_handle}\n"
+                f"score: {highest_score}%\n"
+                f"matches: {match_count}\n"
+            )
+            if primary_match:
+                admin_message += f"primary: {primary_match}\n"
+            if track_url:
+                admin_message += f"\n{track_url}"
 
-        # message for the artist (uploader)
-        artist_message = (
-            f"⚠️ copyright notice for your track on {settings.app.name}\n\n"
-            f"track: '{track_title}'\n"
-            f"match confidence: {highest_score}%\n"
-        )
-        if primary_match:
-            artist_message += f"potential match: {primary_match}\n"
-        artist_message += (
-            "\nif you believe this is an error, please reply to this message. "
-            "otherwise, the track may be removed after review."
-        )
+            # send to artist
+            artist_result = await self._send_dm_to_did(artist_did, artist_message)
+            span.set_attribute("artist_success", artist_result.success)
+            if not artist_result.success:
+                span.set_attribute("artist_error_type", artist_result.error_type)
+                logfire.warn(
+                    "failed to notify artist",
+                    artist_handle=artist_handle,
+                    error_type=artist_result.error_type,
+                    error=artist_result.error,
+                )
 
-        # message for admin
-        admin_message = (
-            f"🚨 copyright flag on {settings.app.name}\n\n"
-            f"track: '{track_title}'\n"
-            f"artist: @{artist_handle}\n"
-            f"score: {highest_score}%\n"
-            f"matches: {match_count}\n"
-        )
-        if primary_match:
-            admin_message += f"primary: {primary_match}\n"
-        if track_url:
-            admin_message += f"\n{track_url}"
+            # send to admin
+            admin_result = None
+            if self.recipient_did:
+                admin_result = await self._send_dm_to_did(
+                    self.recipient_did, admin_message
+                )
+                span.set_attribute("admin_success", admin_result.success)
+                if not admin_result.success:
+                    span.set_attribute("admin_error_type", admin_result.error_type)
+                    logfire.warn(
+                        "failed to notify admin",
+                        error_type=admin_result.error_type,
+                        error=admin_result.error,
+                    )
 
-        # send to both
-        artist_sent = await self._send_dm_to_did(artist_did, artist_message)
-        admin_sent = False
-        if self.recipient_did:
-            admin_sent = await self._send_dm_to_did(self.recipient_did, admin_message)
+            # summary
+            any_success = artist_result.success or (
+                admin_result and admin_result.success
+            )
+            span.set_attribute("any_success", any_success)
 
-        if artist_sent:
-            logger.info(f"sent copyright notification to artist {artist_handle}")
-        if admin_sent:
-            logger.info(f"sent copyright notification to admin for track {track_id}")
+            if artist_result.success:
+                logfire.info(
+                    "sent copyright notification to artist",
+                    artist_handle=artist_handle,
+                    track_id=track_id,
+                )
+            if admin_result and admin_result.success:
+                logfire.info(
+                    "sent copyright notification to admin",
+                    track_id=track_id,
+                )
 
-        return artist_sent or admin_sent
+            return artist_result, admin_result
 
     async def send_image_flag_notification(
         self,