feat: add constellation client for network-wide like counts (#360)

* feat: add constellation client for network-wide like counts

integrates with constellation.microcosm.blue backlink index to query
like counts across the entire atproto network, not just plyr.fm.

- adds get_like_count() for raw queries
- exports get_like_count_safe() from _internal (fallback on error)
- uses settings.atproto.like_collection for environment awareness

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

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

* chore: add user-agent header to constellation requests

per fig's request in constellation readme - be a good citizen

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

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

---------

Co-authored-by: Claude <[e-mail]>

backend/src/backend/_internal/__init__.py

···
     start_oauth_flow,
     update_session_tokens,
 )
+from backend._internal.constellation import get_like_count_safe
 from backend._internal.notifications import notification_service
 from backend._internal.queue import queue_service
 
···
     "create_exchange_token",
     "create_session",
     "delete_session",
+    "get_like_count_safe",
     "get_session",
     "handle_oauth_callback",
     "notification_service",

backend/src/backend/_internal/constellation.py

···
+"""client for constellation atproto backlink index.
+
+constellation indexes backlinks across the atproto network, enabling
+queries like "how many likes does this track have?" across all apps,
+not just plyr.fm.
+
+public instance: https://constellation.microcosm.blue
+source: https://github.com/at-microcosm/microcosm-rs/tree/main/constellation
+"""
+
+import logging
+
+import httpx
+
+from backend.config import settings
+
+logger = logging.getLogger(__name__)
+
+CONSTELLATION_URL = "https://constellation.microcosm.blue"
+USER_AGENT = "plyr.fm (zzstoatzz.io)"
+
+
+async def get_like_count(target_uri: str) -> int:
+    """get network-wide like count for a target record.
+
+    queries constellation's backlink index for all fm.plyr.like records
+    pointing to the target URI.
+
+    args:
+        target_uri: the at:// URI of the record to count likes for
+
+    returns:
+        total like count from across the atproto network
+    """
+    async with httpx.AsyncClient(headers={"User-Agent": USER_AGENT}) as client:
+        resp = await client.get(
+            f"{CONSTELLATION_URL}/links/count",
+            params={
+                "target": target_uri,
+                "collection": settings.atproto.like_collection,
+                "path": ".subject.uri",
+            },
+        )
+        resp.raise_for_status()
+        return resp.json()["count"]
+
+
+async def get_like_count_safe(target_uri: str, fallback: int = 0) -> int:
+    """get like count with fallback on error.
+
+    use this when you don't want constellation failures to break the request.
+    """
+    try:
+        return await get_like_count(target_uri)
+    except Exception as e:
+        logger.warning(f"constellation query failed for {target_uri}: {e}")
+        return fallback

backend/tests/test_constellation.py

···
+"""tests for constellation client."""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from backend._internal.constellation import get_like_count, get_like_count_safe
+
+
[e-mail]
+def mock_settings():
+    """mock settings with like_collection."""
+    with patch("backend._internal.constellation.settings") as mock:
+        mock.atproto.like_collection = "fm.plyr.dev.like"
+        yield mock
+
+
+class TestGetLikeCount:
+    """tests for get_like_count."""
+
+    async def test_returns_count_from_response(self, mock_settings):
+        """should return count from constellation response."""
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"count": 42}
+        mock_response.raise_for_status = MagicMock()
+
+        with patch("backend._internal.constellation.httpx.AsyncClient") as mock_client:
+            mock_client.return_value.__aenter__.return_value.get = AsyncMock(
+                return_value=mock_response
+            )
+
+            result = await get_like_count("at://did:plc:xxx/fm.plyr.track/abc")
+
+            assert result == 42
+
+    async def test_calls_correct_endpoint(self, mock_settings):
+        """should call constellation with correct params."""
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"count": 0}
+        mock_response.raise_for_status = MagicMock()
+
+        with patch("backend._internal.constellation.httpx.AsyncClient") as mock_client:
+            mock_get = AsyncMock(return_value=mock_response)
+            mock_client.return_value.__aenter__.return_value.get = mock_get
+
+            await get_like_count("at://did:plc:xxx/fm.plyr.track/abc")
+
+            mock_get.assert_called_once_with(
+                "https://constellation.microcosm.blue/links/count",
+                params={
+                    "target": "at://did:plc:xxx/fm.plyr.track/abc",
+                    "collection": "fm.plyr.dev.like",
+                    "path": ".subject.uri",
+                },
+            )
+
+    async def test_raises_on_http_error(self, mock_settings):
+        """should raise when constellation returns error."""
+        mock_response = MagicMock()
+        mock_response.raise_for_status.side_effect = Exception("500 error")
+
+        with patch("backend._internal.constellation.httpx.AsyncClient") as mock_client:
+            mock_client.return_value.__aenter__.return_value.get = AsyncMock(
+                return_value=mock_response
+            )
+
+            with pytest.raises(Exception, match="500 error"):
+                await get_like_count("at://did:plc:xxx/fm.plyr.track/abc")
+
+
+class TestGetLikeCountSafe:
+    """tests for get_like_count_safe."""
+
+    async def test_returns_count_on_success(self, mock_settings):
+        """should return count when successful."""
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"count": 10}
+        mock_response.raise_for_status = MagicMock()
+
+        with patch("backend._internal.constellation.httpx.AsyncClient") as mock_client:
+            mock_client.return_value.__aenter__.return_value.get = AsyncMock(
+                return_value=mock_response
+            )
+
+            result = await get_like_count_safe("at://did:plc:xxx/fm.plyr.track/abc")
+
+            assert result == 10
+
+    async def test_returns_fallback_on_error(self, mock_settings):
+        """should return fallback when constellation fails."""
+        with patch("backend._internal.constellation.httpx.AsyncClient") as mock_client:
+            mock_client.return_value.__aenter__.return_value.get = AsyncMock(
+                side_effect=Exception("connection failed")
+            )
+
+            result = await get_like_count_safe(
+                "at://did:plc:xxx/fm.plyr.track/abc", fallback=99
+            )
+
+            assert result == 99
+
+    async def test_default_fallback_is_zero(self, mock_settings):
+        """should default to 0 fallback."""
+        with patch("backend._internal.constellation.httpx.AsyncClient") as mock_client:
+            mock_client.return_value.__aenter__.return_value.get = AsyncMock(
+                side_effect=Exception("connection failed")
+            )
+
+            result = await get_like_count_safe("at://did:plc:xxx/fm.plyr.track/abc")
+
+            assert result == 0