add bin/get_insights_annotations

Author: Jonathan Visser

bin/get_insights_annotations

@@ -0,0 +1 @@
+command

hypernode_api_python/client.py

@@ -23,6 +23,7 @@
 HYPERNODE_API_BRANCHER_APP_ENDPOINT = "/v2/brancher/app/{}/"
 HYPERNODE_API_FPM_STATUS_APP_ENDPOINT = "/v2/nats/{}/hypernode.show-fpm-status"
 HYPERNODE_API_BRANCHER_ENDPOINT = "/v2/brancher/{}/"
+HYPERNODE_API_INSIGHTS_ANNOTATION_LIST_ENDPOINT = "/v2/insights-annotation/"
 HYPERNODE_API_PRODUCT_APP_DETAIL_ENDPOINT = "/v2/product/app/{}/current/"
 HYPERNODE_API_PRODUCT_LIST_ENDPOINT = "/v2/product/"
 HYPERNODE_API_PRODUCT_PRICE_DETAIL_ENDPOINT = "/v2/product/{}/with_price/"
@@ -925,6 +926,38 @@ def get_fpm_status(self, app_name):
             "POST", HYPERNODE_API_FPM_STATUS_APP_ENDPOINT.format(app_name)
         )
 
+    def get_insights_annotations(self, params=None):
+        """
+        List all custom Insights annotations for the Hypernodes you have
+        access to. Only annotations created through the API are listed,
+        system annotations generated from platform events are not included.
+        Example:
+        >    client.get_insights_annotations().json()
+        >    {
+        >        'count': 1,
+        >        'next': None,
+        >        'previous': None,
+        >        'results': [
+        >            {
+        >                'id': 123,
+        >                'name': 'Deployed release 1.2.3',
+        >                'x_axis': 1756384957,
+        >                'app': 'yourhypernodeappname',
+        >                'metrics': 'memory_usage',
+        >                'created': '2025-08-28T12:42:37Z',
+        >                'modified': '2025-08-28T12:42:37Z'
+        >            }
+        >        ]
+        >    }
+
+        :param dict params: Optional query parameters to paginate the
+        results with. An example could be: {'limit': 10, 'offset': 20}
+        :return obj response: The request response object
+        """
+        return self.requests(
+            "GET", HYPERNODE_API_INSIGHTS_ANNOTATION_LIST_ENDPOINT, params=params
+        )
+
     def create_brancher(self, app_name, data):
         """
         Create a new branch (server replica) of your Hypernode.

hypernode_api_python/commands.py

@@ -799,6 +799,54 @@ def destroy_brancher(args=None):
         exit(EX_UNAVAILABLE)
 
 
+def get_insights_annotations(args=None):
+    parser = ArgumentParser(
+        description="""
+List all custom Insights annotations for the Hypernodes you have access to.
+Only annotations created through the API are listed, system annotations
+generated from platform events are not included.
+
+Example:
+$ ./bin/get_insights_annotations
+{
+  "count": 1,
+  "next": null,
+  "previous": null,
+  "results": [
+    {
+      "id": 123,
+      "name": "Deployed release 1.2.3",
+      "x_axis": 1756384957,
+      "app": "yourhypernodeappname",
+      "metrics": "memory_usage",
+      "created": "2025-08-28T12:42:37Z",
+      "modified": "2025-08-28T12:42:37Z"
+    }
+  ]
+}
+""",
+        formatter_class=RawTextHelpFormatter,
+    )
+    parser.add_argument(
+        "--limit",
+        help="Number of results to return per page",
+        type=int,
+    )
+    parser.add_argument(
+        "--offset",
+        help="The initial index from which to return the results",
+        type=int,
+    )
+    args = parser.parse_args(args=args)
+    client = get_client()
+    params = {}
+    if args.limit is not None:
+        params["limit"] = args.limit
+    if args.offset is not None:
+        params["offset"] = args.offset
+    print_response(client.get_insights_annotations(params=params))
+
+
 def get_fpm_status(args=None):
     parser = ArgumentParser(
         description="""

tests/client/test_get_insights_annotations.py

@@ -0,0 +1,45 @@
+from unittest import TestCase
+from unittest.mock import Mock
+
+from hypernode_api_python.client import (
+    HYPERNODE_API_INSIGHTS_ANNOTATION_LIST_ENDPOINT,
+    HypernodeAPIPython,
+)
+
+
+class TestGetInsightsAnnotations(TestCase):
+    def setUp(self):
+        self.client = HypernodeAPIPython(token="my_token")
+        self.mock_request = Mock()
+        self.client.requests = self.mock_request
+
+    def test_insights_annotation_list_endpoint_is_correct(self):
+        self.assertEqual(
+            "/v2/insights-annotation/",
+            HYPERNODE_API_INSIGHTS_ANNOTATION_LIST_ENDPOINT,
+        )
+
+    def test_calls_get_insights_annotations_endpoint_properly(self):
+        self.client.get_insights_annotations()
+
+        self.mock_request.assert_called_once_with(
+            "GET", "/v2/insights-annotation/", params=None
+        )
+
+    def test_calls_get_insights_annotations_endpoint_with_pagination_params(self):
+        params = {"limit": 10, "offset": 20}
+        self.client.get_insights_annotations(params=params)
+
+        self.mock_request.assert_called_once_with(
+            "GET", "/v2/insights-annotation/", params=params
+        )
+
+    def test_returns_get_insights_annotations_response(self):
+        response = Mock()
+        response.status_code = 200
+        self.mock_request.return_value = response
+
+        self.assertEqual(
+            self.client.get_insights_annotations(),
+            self.mock_request.return_value,
+        )

tests/commands/test_get_insights_annotations.py

@@ -0,0 +1,35 @@
+from hypernode_api_python.commands import get_insights_annotations
+from tests.testcase import TestCase
+
+
+class TestGetInsightsAnnotations(TestCase):
+    def setUp(self):
+        self.print_response = self.set_up_patch(
+            "hypernode_api_python.commands.print_response"
+        )
+        self.get_client = self.set_up_patch("hypernode_api_python.commands.get_client")
+        self.client = self.get_client.return_value
+
+    def test_get_insights_annotations_gets_client(self):
+        get_insights_annotations([])
+
+        self.get_client.assert_called_once_with()
+
+    def test_get_insights_annotations_gets_insights_annotations(self):
+        get_insights_annotations([])
+
+        self.client.get_insights_annotations.assert_called_once_with(params={})
+
+    def test_get_insights_annotations_passes_pagination_params(self):
+        get_insights_annotations(["--limit", "10", "--offset", "20"])
+
+        self.client.get_insights_annotations.assert_called_once_with(
+            params={"limit": 10, "offset": 20}
+        )
+
+    def test_get_insights_annotations_prints_response(self):
+        get_insights_annotations([])
+
+        self.print_response.assert_called_once_with(
+            self.client.get_insights_annotations.return_value
+        )