feat: add friends count sensors (Phase 9)

Add social sensors for friend tracking:
- sensor.rouvy_friends_count (total friends)
- sensor.rouvy_friends_online (currently online)

Implementation:
- FriendsSummary model for friends.data endpoint
- extract_friends_model() parser
- async_get_friends() API method
- Coordinator fetches friends summary

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mikejhill

custom_components/rouvy/api.py

@@ -20,6 +20,7 @@
     Challenge,
     ConnectedApp,
     Event,
+    FriendsSummary,
     Route,
     TrainingZones,
     UserProfile,
@@ -32,6 +33,7 @@
     extract_challenges_model,
     extract_connected_apps_model,
     extract_events_model,
+    extract_friends_model,
     extract_routes_model,
     extract_training_zones_model,
     extract_user_profile_model,
@@ -228,6 +230,11 @@ async def async_get_activity_stats(self, year: int, month: int) -> list[WeeklyAc
         )
         return extract_activity_stats_model(text)
 
+    async def async_get_friends(self) -> FriendsSummary:
+        """Fetch friends summary."""
+        text = await self._request("GET", "friends.data")
+        return extract_friends_model(text)
+
     async def async_get_challenges(self) -> list[Challenge]:
         """Fetch available challenges."""
         text = await self._request("GET", "challenges/status/available.data")

custom_components/rouvy/api_client/models.py

@@ -177,6 +177,14 @@ class CareerStats:
     coins: int = 0
 
 
+@dataclass(frozen=True)
+class FriendsSummary:
+    """Summary of the user's friends list."""
+
+    total_friends: int = 0
+    online_friends: int = 0
+
+
 @dataclass(frozen=True)
 class RouvyCoordinatorData:
     """Composite data object held by the coordinator.
@@ -195,3 +203,4 @@ class RouvyCoordinatorData:
     favorite_routes: list[Route] = field(default_factory=list)
     upcoming_events: list[Event] = field(default_factory=list)
     career: CareerStats | None = None
+    friends: FriendsSummary | None = None

custom_components/rouvy/api_client/parser.py

@@ -29,6 +29,7 @@
         Challenge,
         ConnectedApp,
         Event,
+        FriendsSummary,
         Route,
         TrainingZones,
         UserProfile,
@@ -835,3 +836,41 @@ def _pick_float(*keys: str) -> float:
         level=_pick_int("level"),
         coins=_pick_int("coins"),
     )
+
+
+def extract_friends_model(response_text: str) -> FriendsSummary:
+    """Extract a FriendsSummary from a friends.data response.
+
+    Searches for known keys that may contain a friends list, counts
+    the total entries, and counts those with an online/status indicator.
+    """
+    from .models import FriendsSummary
+
+    if not response_text or not response_text.strip():
+        return FriendsSummary()
+
+    decoder = TurboStreamDecoder()
+    decoded = decoder.decode(response_text)
+    array_data: list[Any] = decoded if isinstance(decoded, list) else []
+
+    friends_list: list[Any] | None = None
+    for key in ("friends", "friendList", "friendsList"):
+        candidate = _find_key_value(array_data, key)
+        if isinstance(candidate, list):
+            friends_list = candidate
+            break
+
+    if not friends_list:
+        return FriendsSummary()
+
+    total = len(friends_list)
+    online = 0
+    for item in friends_list:
+        resolved = _resolve_index(item, decoder.index_map)
+        if not isinstance(resolved, dict):
+            continue
+        status = resolved.get("status") or resolved.get("online")
+        if status in (True, "online", "active"):
+            online += 1
+
+    return FriendsSummary(total_friends=total, online_friends=online)

custom_components/rouvy/coordinator.py

@@ -109,6 +109,13 @@ async def _async_update_data(self) -> RouvyCoordinatorData:
             except Exception:
                 _LOGGER.debug("Failed to fetch career stats, continuing without", exc_info=True)
 
+            # Fetch friends summary
+            friends = None
+            try:
+                friends = await client.async_get_friends()
+            except Exception:
+                _LOGGER.debug("Failed to fetch friends, continuing without", exc_info=True)
+
             self._consecutive_auth_failures = 0
             _LOGGER.debug("Coordinator update successful")
             return RouvyCoordinatorData(
@@ -121,6 +128,7 @@ async def _async_update_data(self) -> RouvyCoordinatorData:
                 favorite_routes=favorite_routes,
                 upcoming_events=upcoming_events,
                 career=career,
+                friends=friends,
             )
         except AuthenticationError as err:
             self._consecutive_auth_failures += 1

custom_components/rouvy/sensor.py

@@ -304,6 +304,19 @@ class RouvySensorDescription(SensorEntityDescription):
             else None
         ),
     ),
+    # Friends sensors
+    RouvySensorDescription(
+        key="friends_count",
+        translation_key="friends_count",
+        state_class=SensorStateClass.MEASUREMENT,
+        value_fn=lambda d: d.friends.total_friends if d.friends else None,
+    ),
+    RouvySensorDescription(
+        key="friends_online",
+        translation_key="friends_online",
+        state_class=SensorStateClass.MEASUREMENT,
+        value_fn=lambda d: d.friends.online_friends if d.friends else None,
+    ),
 )
 
 

custom_components/rouvy/strings.json

@@ -60,7 +60,9 @@
       "career_level": { "name": "Career Level" },
       "total_xp": { "name": "Total XP" },
       "total_coins": { "name": "Total Coins" },
-      "career_total_distance": { "name": "Career Total Distance" }
+      "career_total_distance": { "name": "Career Total Distance" },
+      "friends_count": { "name": "Friends" },
+      "friends_online": { "name": "Online Friends" }
     }
   }
 }

custom_components/rouvy/translations/en.json

@@ -60,7 +60,9 @@
       "career_level": { "name": "Career Level" },
       "total_xp": { "name": "Total XP" },
       "total_coins": { "name": "Total Coins" },
-      "career_total_distance": { "name": "Career Total Distance" }
+      "career_total_distance": { "name": "Career Total Distance" },
+      "friends_count": { "name": "Friends" },
+      "friends_online": { "name": "Online Friends" }
     }
   }
 }

tests/test_ha_integration.py

@@ -18,6 +18,7 @@
 from custom_components.rouvy.api_client.models import (
     ActivitySummary,
     CareerStats,
+    FriendsSummary,
     TrainingZones,
     UserProfile,
 )
@@ -73,6 +74,7 @@ def _mock_client(profile: UserProfile | None = None) -> AsyncMock:
     client.async_get_connected_apps = AsyncMock(return_value=[])
     client.async_get_activity_summary = AsyncMock(return_value=ActivitySummary())
     client.async_get_favorite_routes = AsyncMock(return_value=[])
+    client.async_get_friends = AsyncMock(return_value=FriendsSummary())
     client.async_update_user_settings = AsyncMock()
     client.async_get_events = AsyncMock(return_value=[])
     client.async_register_event = AsyncMock(return_value=True)
@@ -381,17 +383,17 @@ async def test_zero_weight_shows_unknown(self, hass: HomeAssistant) -> None:
         assert state.state == "unknown"
 
     async def test_all_sensors_created(self, hass: HomeAssistant) -> None:
-        """Test that all 31 sensor entities are created.
+        """Test that all 33 sensor entities are created.
 
         6 profile + 6 weekly + 2 challenges + 2 zones
-        + 2 connected apps + 5 activity + 2 routes + 2 events + 4 career.
+        + 2 connected apps + 5 activity + 2 routes + 2 events + 4 career + 2 friends.
         """
         await self._setup(hass)
         sensor_states = [
             s for s in hass.states.async_all() if s.entity_id.startswith("sensor.rouvy")
         ]
-        assert len(sensor_states) == 31, (
-            f"Expected 31 sensors, got {len(sensor_states)}: {[s.entity_id for s in sensor_states]}"
+        assert len(sensor_states) == 33, (
+            f"Expected 33 sensors, got {len(sensor_states)}: {[s.entity_id for s in sensor_states]}"
         )
 
 

tests/test_ha_sensor.py

@@ -13,6 +13,7 @@
     Challenge,
     ConnectedApp,
     Event,
+    FriendsSummary,
     Route,
     RouvyCoordinatorData,
     TrainingZones,
@@ -528,6 +529,7 @@ def test_empty_returns_zero(self) -> None:
         assert desc.value_fn(d) == 0
 
 
+# ===================================================================
 # ===================================================================
 # ===================================================================
 # Activity summary sensor helpers
@@ -949,3 +951,65 @@ def test_no_career_returns_none(self) -> None:
         d = _make_data_with_career(None)
         desc = next(s for s in SENSOR_DESCRIPTIONS if s.key == "career_total_distance")
         assert desc.value_fn(d) is None
+
+
+# ===================================================================
+# Friends sensor helpers
+# ===================================================================
+
+
+def _make_data_with_friends(
+    friends: FriendsSummary | None = None,
+) -> RouvyCoordinatorData:
+    """Create coordinator data with friends summary."""
+    return RouvyCoordinatorData(profile=_make_profile(), friends=friends)
+
+
+class TestFriendsCountSensor:
+    """Verify friends_count sensor value extraction."""
+
+    def test_returns_total(self) -> None:
+        d = _make_data_with_friends(FriendsSummary(total_friends=42, online_friends=5))
+        from custom_components.rouvy.sensor import SENSOR_DESCRIPTIONS
+
+        desc = next(s for s in SENSOR_DESCRIPTIONS if s.key == "friends_count")
+        assert desc.value_fn(d) == 42
+
+    def test_none_friends_returns_none(self) -> None:
+        d = _make_data_with_friends(None)
+        from custom_components.rouvy.sensor import SENSOR_DESCRIPTIONS
+
+        desc = next(s for s in SENSOR_DESCRIPTIONS if s.key == "friends_count")
+        assert desc.value_fn(d) is None
+
+    def test_zero_friends(self) -> None:
+        d = _make_data_with_friends(FriendsSummary())
+        from custom_components.rouvy.sensor import SENSOR_DESCRIPTIONS
+
+        desc = next(s for s in SENSOR_DESCRIPTIONS if s.key == "friends_count")
+        assert desc.value_fn(d) == 0
+
+
+class TestFriendsOnlineSensor:
+    """Verify friends_online sensor value extraction."""
+
+    def test_returns_online_count(self) -> None:
+        d = _make_data_with_friends(FriendsSummary(total_friends=42, online_friends=5))
+        from custom_components.rouvy.sensor import SENSOR_DESCRIPTIONS
+
+        desc = next(s for s in SENSOR_DESCRIPTIONS if s.key == "friends_online")
+        assert desc.value_fn(d) == 5
+
+    def test_none_friends_returns_none(self) -> None:
+        d = _make_data_with_friends(None)
+        from custom_components.rouvy.sensor import SENSOR_DESCRIPTIONS
+
+        desc = next(s for s in SENSOR_DESCRIPTIONS if s.key == "friends_online")
+        assert desc.value_fn(d) is None
+
+    def test_zero_online(self) -> None:
+        d = _make_data_with_friends(FriendsSummary(total_friends=10, online_friends=0))
+        from custom_components.rouvy.sensor import SENSOR_DESCRIPTIONS
+
+        desc = next(s for s in SENSOR_DESCRIPTIONS if s.key == "friends_online")
+        assert desc.value_fn(d) == 0

tests/test_parser.py

@@ -1121,6 +1121,7 @@ def test_missing_fields_use_defaults(self) -> None:
         assert result[0].segments == []
 
 
+# ===================================================================
 # ===================================================================
 # extract_routes_model
 # ===================================================================
@@ -1447,3 +1448,85 @@ def test_partial_data_fills_defaults(self) -> None:
         assert result.level == 5
         assert result.coins == 0
         assert result.total_distance_m == 0.0
+
+
+# ===================================================================
+# extract_friends_model
+# ===================================================================
+
+
+def _build_friends_response(
+    friends: list[dict[str, Any]] | None = None,
+    key: str = "friends",
+) -> str:
+    """Build a synthetic turbo-stream response for friends.data."""
+    if friends is None:
+        friends = [
+            {"name": "Alice", "status": "online"},
+            {"name": "Bob", "status": "offline"},
+            {"name": "Charlie", "online": True},
+        ]
+    return json.dumps([key, friends])
+
+
+class TestExtractFriends:
+    """Verify extract_friends_model with synthetic data."""
+
+    def test_counts_total_friends(self) -> None:
+        from custom_components.rouvy.api_client.parser import extract_friends_model
+
+        result = extract_friends_model(_build_friends_response())
+        assert result.total_friends == 3
+
+    def test_counts_online_friends(self) -> None:
+        from custom_components.rouvy.api_client.parser import extract_friends_model
+
+        result = extract_friends_model(_build_friends_response())
+        assert result.online_friends == 2
+
+    def test_empty_list_returns_zero(self) -> None:
+        from custom_components.rouvy.api_client.parser import extract_friends_model
+
+        result = extract_friends_model(_build_friends_response(friends=[]))
+        assert result.total_friends == 0
+        assert result.online_friends == 0
+
+    def test_empty_response_returns_default(self) -> None:
+        from custom_components.rouvy.api_client.parser import extract_friends_model
+
+        result = extract_friends_model("")
+        assert result.total_friends == 0
+        assert result.online_friends == 0
+
+    def test_no_friends_key_returns_default(self) -> None:
+        from custom_components.rouvy.api_client.parser import extract_friends_model
+
+        result = extract_friends_model(json.dumps(["other_key", []]))
+        assert result.total_friends == 0
+        assert result.online_friends == 0
+
+    def test_friend_list_key_variant(self) -> None:
+        from custom_components.rouvy.api_client.parser import extract_friends_model
+
+        friends = [{"name": "X", "status": "online"}]
+        result = extract_friends_model(_build_friends_response(friends=friends, key="friendList"))
+        assert result.total_friends == 1
+        assert result.online_friends == 1
+
+    def test_active_status_counted_as_online(self) -> None:
+        from custom_components.rouvy.api_client.parser import extract_friends_model
+
+        friends = [{"name": "D", "status": "active"}]
+        result = extract_friends_model(_build_friends_response(friends=friends))
+        assert result.online_friends == 1
+
+    def test_all_offline(self) -> None:
+        from custom_components.rouvy.api_client.parser import extract_friends_model
+
+        friends = [
+            {"name": "A", "status": "offline"},
+            {"name": "B", "status": "away"},
+        ]
+        result = extract_friends_model(_build_friends_response(friends=friends))
+        assert result.total_friends == 2
+        assert result.online_friends == 0