From 971384b50e2e4324fecd480a8abaa4cb8b7d78be Mon Sep 17 00:00:00 2001
From: Matias Bordese <mbordese@gmail.com>
Date: Mon, 11 Sep 2023 10:25:00 -0300
Subject: [PATCH] Update internal alert group details API docs (#2995)

Related to https://github.com/grafana/oncall/issues/2982
---
 engine/apps/alerts/models/alert_group.py | 18 ++++++-
 engine/apps/api/views/alert_group.py     | 60 ++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 1 deletion(-)

diff --git a/engine/apps/alerts/models/alert_group.py b/engine/apps/alerts/models/alert_group.py
index fb64d83c..81a11ce1 100644
--- a/engine/apps/alerts/models/alert_group.py
+++ b/engine/apps/alerts/models/alert_group.py
@@ -62,6 +62,22 @@ def generate_public_primary_key_for_alert_group():
     return new_public_primary_key
 
 
+class LogRecordUser(typing.TypedDict):
+    username: str
+    pk: str
+    avatar: str
+    avatar_full: str
+
+
+class LogRecords(typing.TypedDict):
+    time: str  # humanized delta relative to now
+    action: str  # human-friendly description
+    realm: typing.Literal["user_notification", "alert_group", "resolution_note"]
+    type: int  # depending on realm, check type choices
+    created_at: str  # timestamp
+    author: LogRecordUser
+
+
 class Permalinks(typing.TypedDict):
     slack: typing.Optional[str]
     telegram: typing.Optional[str]
@@ -1741,7 +1757,7 @@ class AlertGroup(AlertGroupSlackRenderingMixin, EscalationSnapshotMixin, models.
         else:
             return "Acknowledged"
 
-    def render_after_resolve_report_json(self):
+    def render_after_resolve_report_json(self) -> list[LogRecords]:
         from apps.alerts.models import AlertGroupLogRecord, ResolutionNote
         from apps.base.models import UserNotificationPolicyLogRecord
 
diff --git a/engine/apps/api/views/alert_group.py b/engine/apps/api/views/alert_group.py
index c507d55c..14b1bf41 100644
--- a/engine/apps/api/views/alert_group.py
+++ b/engine/apps/api/views/alert_group.py
@@ -354,6 +354,66 @@ class AlertGroupView(
         obj = self.enrich([obj])[0]
         return obj
 
+    def retrieve(self, request, pk, *args, **kwargs):
+        """Return alert group details.
+
+        It is worth mentioning that `render_after_resolve_report_json` property will return a list
+        of log entries including actions involving the alert group, notifications triggered for a user
+        and resolution notes updates.
+
+        A few additional notes about the possible values for each key in the logs:
+
+        - `time`: humanized time delta respect to now when the action took place
+        - `action`: human-readable description of the action
+        - `realm`: resource involved in the action; one of three possible values:
+        `alert_group`, `user_notification`, `resolution_note`
+        - `type`: integer value indicating the type of action (see below)
+        - `created_at`: timestamp corresponding to when the action happened
+        - `author`: details about the user performing the action
+
+        Possible `type` values depending on the realm value:
+
+        For `alert_group`:
+        - 0: Acknowledged
+        - 1: Unacknowledged
+        - 2: Invite
+        - 3: Stop invitation
+        - 4: Re-invite
+        - 5: Escalation triggered
+        - 6: Invitation triggered
+        - 7: Silenced
+        - 8: Attached
+        - 9: Unattached
+        - 10: Custom button triggered
+        - 11: Unacknowledged by timeout
+        - 12: Failed attachment
+        - 13: Incident resolved
+        - 14: Incident unresolved
+        - 15: Unsilenced
+        - 16: Escalation finished
+        - 17: Escalation failed
+        - 18: Acknowledge reminder triggered
+        - 19: Wiped
+        - 20: Deleted
+        - 21: Incident registered
+        - 22: A route is assigned to the incident
+        - 23: Trigger direct paging escalation
+        - 24: Unpage a user
+        - 25: Restricted
+
+        For `user_notification`:
+        - 0: Personal notification triggered
+        - 1: Personal notification finished
+        - 2: Personal notification success,
+        - 3: Personal notification failed
+
+        For `resolution_note`:
+        - 0: slack
+        - 1: web
+
+        """
+        return super().retrieve(request, pk, *args, **kwargs)
+
     def enrich(self, alert_groups):
         """
         This method performs select_related and prefetch_related (using setup_eager_loading) as well as in-memory joins