feat(alerting): Add subscriptions alerts API

lago_python_client/mixins.py

@@ -395,14 +395,15 @@ class NestedCreateCommandMixin(Generic[_M]):
     def create(
         self: _ClientMixin[_M],
         *args: Union[str, BaseModel],
+        options: QueryPairs = None,
         timeout: Optional[httpx.Timeout] = None,
     ) -> Optional[_M]:
         """Execute `create` command."""
         *parent_ids, input_object = args
 
         # Send request and save response
         api_response: Response = send_post_request(
-            url=make_url(origin=self.base_url, path_parts=self.api_resource(*parent_ids)),
+            url=make_url(origin=self.base_url, path_parts=self.api_resource(*parent_ids), query_pairs=options),
             content=to_json(
                 {
                     self.ROOT_NAME: input_object.dict(exclude_none=True),
@@ -430,6 +431,7 @@ class NestedUpdateCommandMixin(Generic[_M]):
     def update(
         self: _ClientMixin[_M],
         *args: Union[str, BaseModel],
+        options: QueryPairs = None,
         timeout: Optional[httpx.Timeout] = None,
     ) -> _M:
         """Execute `update` command."""
@@ -440,6 +442,7 @@ def update(
             url=make_url(
                 origin=self.base_url,
                 path_parts=self.api_resource(*parent_ids) + (resource_id,),
+                query_pairs=options,
             ),
             content=to_json(
                 {
@@ -464,6 +467,7 @@ class NestedDestroyCommandMixin(Generic[_M]):
     def destroy(
         self: _ClientMixin[_M],
         *args: str,
+        options: QueryPairs = None,
         timeout: Optional[httpx.Timeout] = None,
     ) -> BaseModel:
         """Execute `destroy` command."""
@@ -474,6 +478,7 @@ def destroy(
             url=make_url(
                 origin=self.base_url,
                 path_parts=self.api_resource(*parent_ids) + (resource_id,),
+                query_pairs=options,
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
@@ -493,6 +498,7 @@ class NestedFindCommandMixin(Generic[_M]):
     def find(
         self: _ClientMixin[_M],
         *args: str,
+        options: QueryPairs = None,
         timeout: Optional[httpx.Timeout] = None,
     ) -> _M:
         """Execute `find` command."""
@@ -503,6 +509,7 @@ def find(
             url=make_url(
                 origin=self.base_url,
                 path_parts=self.api_resource(*parent_ids) + (resource_id,),
+                query_pairs=options,
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,

lago_python_client/subscriptions/alert_client.py

@@ -0,0 +1,86 @@
+from typing import Any, ClassVar, Mapping, Optional, Type
+
+import httpx
+
+from ..base_client import BaseClient
+from ..mixins import (
+    NestedCreateCommandMixin,
+    NestedDestroyCommandMixin,
+    NestedFindAllCommandMixin,
+    NestedFindCommandMixin,
+    NestedUpdateCommandMixin,
+)
+from ..models.alert import Alert, AlertResponse
+from ..services.request import QueryPairs
+
+
+class SubscriptionAlertClient(
+    NestedCreateCommandMixin[AlertResponse],
+    NestedUpdateCommandMixin[AlertResponse],
+    NestedDestroyCommandMixin[AlertResponse],
+    NestedFindCommandMixin[AlertResponse],
+    NestedFindAllCommandMixin[AlertResponse],
+    BaseClient,
+):
+    API_RESOURCE: ClassVar[str] = "alerts"
+    RESPONSE_MODEL: ClassVar[Type[AlertResponse]] = AlertResponse
+    ROOT_NAME: ClassVar[str] = "alert"
+
+    def api_resource(self, subscription_id: str) -> tuple[str]:
+        return ("subscriptions", subscription_id, "alerts")
+
+    # The API only looks up active subscriptions unless `subscription_status` is given.
+    def create(
+        self,
+        subscription_id: str,
+        input_object: Alert,
+        subscription_status: Optional[str] = None,
+        timeout: Optional[httpx.Timeout] = None,
+    ) -> Optional[AlertResponse]:
+        return super().create(
+            subscription_id, input_object, options=_status_query(subscription_status), timeout=timeout
+        )
+
+    def update(
+        self,
+        subscription_id: str,
+        code: str,
+        input_object: Alert,
+        subscription_status: Optional[str] = None,
+        timeout: Optional[httpx.Timeout] = None,
+    ) -> AlertResponse:
+        return super().update(
+            subscription_id, code, input_object, options=_status_query(subscription_status), timeout=timeout
+        )
+
+    def destroy(
+        self,
+        subscription_id: str,
+        code: str,
+        subscription_status: Optional[str] = None,
+        timeout: Optional[httpx.Timeout] = None,
+    ) -> AlertResponse:
+        return super().destroy(subscription_id, code, options=_status_query(subscription_status), timeout=timeout)
+
+    def find(
+        self,
+        subscription_id: str,
+        code: str,
+        subscription_status: Optional[str] = None,
+        timeout: Optional[httpx.Timeout] = None,
+    ) -> AlertResponse:
+        return super().find(subscription_id, code, options=_status_query(subscription_status), timeout=timeout)
+
+    def find_all(
+        self,
+        subscription_id: str,
+        options: QueryPairs = None,
+        subscription_status: Optional[str] = None,
+        timeout: Optional[httpx.Timeout] = None,
+    ) -> Mapping[str, Any]:
+        query = {**dict(options or {}), **_status_query(subscription_status)}
+        return super().find_all(subscription_id, options=query, timeout=timeout)
+
+
+def _status_query(subscription_status: Optional[str]) -> dict:
+    return {} if subscription_status is None else {"subscription_status": subscription_status}

lago_python_client/subscriptions/clients.py

@@ -2,6 +2,7 @@
 
 from ..base_client import BaseClient
 from ..base_model import BaseModel
+from ..functools_ext import callable_cached_property
 from ..mixins import (
     CreateCommandMixin,
     DestroyCommandMixin,
@@ -29,6 +30,7 @@
     prepare_object_response,
     verify_response,
 )
+from .alert_client import SubscriptionAlertClient
 
 
 class SubscriptionClient(
@@ -43,6 +45,12 @@ class SubscriptionClient(
     RESPONSE_MODEL: ClassVar[Type[SubscriptionResponse]] = SubscriptionResponse
     ROOT_NAME: ClassVar[str] = "subscription"
 
+    @callable_cached_property
+    def alerts(self) -> SubscriptionAlertClient:
+        return SubscriptionAlertClient(
+            self.base_url, self.api_key, rate_limit_retry_config=self.rate_limit_retry_config
+        )
+
     def lifetime_usage(self, resource_id: str) -> LifetimeUsageResponse:
         api_response: Response = send_get_request(
             url=make_url(

tests/fixtures/subscription_alert.json

@@ -0,0 +1,46 @@
+{
+  "alert": {
+    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+    "lago_organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+    "external_subscription_id": "subscription_id",
+    "lago_wallet_id": null,
+    "wallet_code": null,
+    "alert_type": "billable_metric_current_usage_amount",
+    "code": "storage_threshold_alert",
+    "name": "Storage Usage Alert",
+    "billable_metric": {
+      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+      "name": "Storage",
+      "code": "storage",
+      "description": "GB of storage used in my application",
+      "recurring": false,
+      "rounding_function": "round",
+      "rounding_precision": 2,
+      "created_at": "2022-09-14T16:35:31Z",
+      "expression": "round((ended_at - started_at) * units)",
+      "field_name": "gb",
+      "aggregation_type": "sum_agg",
+      "weighted_interval": "seconds",
+      "filters": [
+        {
+          "key": "region",
+          "values": [
+            "us-east-1"
+          ]
+        }
+      ]
+    },
+    "previous_value": 1000,
+    "direction": "increasing",
+    "thresholds": [
+      {
+        "code": "warn",
+        "recurring": false,
+        "value": "99.0",
+        "notify_on": ["triggered", "resolved"]
+      }
+    ],
+    "created_at": "2025-03-20T10:00:00Z",
+    "last_processed_at": "2025-05-19T10:04:21Z"
+  }
+}

tests/fixtures/subscription_alert_index.json

@@ -0,0 +1,55 @@
+{
+  "alerts": [
+    {
+      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+      "lago_organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+      "external_subscription_id": "subscription_id",
+      "lago_wallet_id": null,
+      "wallet_code": null,
+      "alert_type": "billable_metric_current_usage_amount",
+      "code": "storage_threshold_alert",
+      "name": "Storage Usage Alert",
+      "billable_metric": {
+        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+        "name": "Storage",
+        "code": "storage",
+        "description": "GB of storage used in my application",
+        "recurring": false,
+        "rounding_function": "round",
+        "rounding_precision": 2,
+        "created_at": "2022-09-14T16:35:31Z",
+        "expression": "round((ended_at - started_at) * units)",
+        "field_name": "gb",
+        "aggregation_type": "sum_agg",
+        "weighted_interval": "seconds",
+        "filters": [
+          {
+            "key": "region",
+            "values": [
+              "us-east-1"
+            ]
+          }
+        ]
+      },
+      "previous_value": 1000,
+      "direction": "increasing",
+      "thresholds": [
+        {
+          "code": "warn",
+          "recurring": false,
+          "value": "99.0",
+          "notify_on": ["triggered", "resolved"]
+        }
+      ],
+      "created_at": "2025-03-20T10:00:00Z",
+      "last_processed_at": "2025-05-19T10:04:21Z"
+    }
+  ],
+  "meta": {
+    "current_page": 1,
+    "next_page": 2,
+    "prev_page": null,
+    "total_pages": 4,
+    "total_count": 70
+  }
+}