Explain remote service responses in plain English

backend/app/clients/jellyfin.py

@@ -1,10 +1,26 @@
 from typing import Any, Dict, Optional
 import httpx
 import time
-from .base import ApiClient
+from .base import ApiClient, _operation_error_message
 from ..services.operation_progress import finish_remote_call, start_remote_call
 
 
+def _availability_message(result: Any) -> str:
+    if not isinstance(result, dict):
+        return "Jellyfin did not return any matching library items."
+    total = result.get("TotalRecordCount")
+    items = result.get("Items")
+    available = (
+        (isinstance(total, int) and total > 0)
+        or (isinstance(items, list) and len(items) > 0)
+    )
+    return (
+        "The title is available to watch in Jellyfin."
+        if available
+        else "The title is not currently available in Jellyfin."
+    )
+
+
 class JellyfinClient(ApiClient):
     def __init__(self, base_url: Optional[str], api_key: Optional[str]):
         super().__init__(base_url, api_key)
@@ -189,7 +205,7 @@ class JellyfinClient(ApiClient):
                 operation_event_id,
                 success=True,
                 status_code=response.status_code,
-                message=f"Jellyfin returned library availability in {duration_ms / 1000:.1f}s.",
+                message=_availability_message(result),
             )
             return result
         except Exception as exc:
@@ -199,7 +215,7 @@ class JellyfinClient(ApiClient):
                 operation_event_id,
                 success=False,
                 status_code=status_code,
-                message=f"Jellyfin returned an error after {duration_ms / 1000:.1f}s.",
+                message=_operation_error_message("Jellyfin", status_code),
             )
             raise
 
@@ -241,7 +257,7 @@ class JellyfinClient(ApiClient):
                 operation_event_id,
                 success=True,
                 status_code=response.status_code,
-                message=f"Jellyfin accepted the library refresh in {duration_ms / 1000:.1f}s.",
+                message="Jellyfin accepted the library refresh and is scanning for new media.",
             )
         except Exception as exc:
             duration_ms = round((time.perf_counter() - started_at) * 1000, 2)
@@ -250,6 +266,6 @@ class JellyfinClient(ApiClient):
                 operation_event_id,
                 success=False,
                 status_code=status_code,
-                message=f"Jellyfin returned an error after {duration_ms / 1000:.1f}s.",
+                message=_operation_error_message("Jellyfin", status_code),
             )
             raise