Add users engagement API methods (#369)

Author: jadolg

rocketchat_API/APISections/users_engagement.py

@@ -0,0 +1,61 @@
+from rocketchat_API.APISections.base import RocketChatBase
+
+
+class RocketChatUsersEngagement(RocketChatBase):
+    def engagement_dashboard_new_users(self, start, end, **kwargs):
+        """
+        Retrieve the metrics of newly registered users during a specific period.
+        Permission required: view-engagement-dashboard
+        """
+        return self.call_api_get(
+            "engagement-dashboard/users/new-users",
+            start=start,
+            end=end,
+            kwargs=kwargs,
+        )
+
+    def engagement_dashboard_active_users(self, start, end, **kwargs):
+        """
+        Retrieve the metrics of active users in the workspace during a specific period.
+        Permission required: view-engagement-dashboard
+        """
+        return self.call_api_get(
+            "engagement-dashboard/users/active-users",
+            start=start,
+            end=end,
+            kwargs=kwargs,
+        )
+
+    def engagement_dashboard_chat_busier_hourly(self, start, **kwargs):
+        """
+        Retrieve hourly data when chat is busier.
+        Permission required: view-engagement-dashboard
+        """
+        return self.call_api_get(
+            "engagement-dashboard/users/chat-busier/hourly-data",
+            start=start,
+            kwargs=kwargs,
+        )
+
+    def engagement_dashboard_chat_busier_weekly(self, start, **kwargs):
+        """
+        Retrieves weekly data when chat is busier.
+        Permission required: view-engagement-dashboard
+        """
+        return self.call_api_get(
+            "engagement-dashboard/users/chat-busier/weekly-data",
+            start=start,
+            kwargs=kwargs,
+        )
+
+    def engagement_dashboard_users_by_time_of_day(self, start, end, **kwargs):
+        """
+        Retrieve users by hours at a particular time of the day in a week.
+        Permission required: view-engagement-dashboard
+        """
+        return self.call_api_get(
+            "engagement-dashboard/users/users-by-time-of-the-day-in-a-week",
+            start=start,
+            end=end,
+            kwargs=kwargs,
+        )

rocketchat_API/rocketchat.py

@@ -20,6 +20,7 @@
 from rocketchat_API.APISections.subscriptions import RocketChatSubscriptions
 from rocketchat_API.APISections.teams import RocketChatTeams
 from rocketchat_API.APISections.users import RocketChatUsers
+from rocketchat_API.APISections.users_engagement import RocketChatUsersEngagement
 
 
 class RocketChat(
@@ -43,5 +44,6 @@ class RocketChat(
     RocketChatSubscriptions,
     RocketChatTeams,
     RocketChatUsers,
+    RocketChatUsersEngagement,
 ):
     pass

tests/test_users_engagement.py

@@ -0,0 +1,61 @@
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+
+@pytest.fixture()
+def date_range():
+    end = datetime.now(timezone.utc)
+    start = end - timedelta(days=7)
+    return {
+        "start": start.strftime("%Y-%m-%dT%H:%M:%S.000Z"),
+        "end": end.strftime("%Y-%m-%dT%H:%M:%S.000Z"),
+    }
+
+
+def test_engagement_dashboard_new_users(logged_rocket, skip_if_no_license, date_range):
+    result = logged_rocket.engagement_dashboard_new_users(
+        start=date_range["start"], end=date_range["end"]
+    )
+    assert "days" in result
+    assert "period" in result
+    assert "yesterday" in result
+    assert isinstance(result["days"], list)
+    assert isinstance(result["period"]["count"], int)
+
+
+def test_engagement_dashboard_active_users(
+    logged_rocket, skip_if_no_license, date_range
+):
+    result = logged_rocket.engagement_dashboard_active_users(
+        start=date_range["start"], end=date_range["end"]
+    )
+    assert "month" in result
+
+
+def test_engagement_dashboard_chat_busier_hourly(
+    logged_rocket, skip_if_no_license, date_range
+):
+    result = logged_rocket.engagement_dashboard_chat_busier_hourly(
+        start=date_range["start"]
+    )
+    assert "hours" in result
+
+
+def test_engagement_dashboard_chat_busier_weekly(
+    logged_rocket, skip_if_no_license, date_range
+):
+    result = logged_rocket.engagement_dashboard_chat_busier_weekly(
+        start=date_range["start"]
+    )
+    assert "month" in result
+
+
+def test_engagement_dashboard_users_by_time_of_day(
+    logged_rocket, skip_if_no_license, date_range
+):
+    result = logged_rocket.engagement_dashboard_users_by_time_of_day(
+        start=date_range["start"], end=date_range["end"]
+    )
+    assert "week" in result
+    assert isinstance(result["week"], list)