changes

Author: haydencarroll-NS1

CHANGELOG.md

@@ -1,7 +1,7 @@
 ## 0.25.0 (August 19th, 2025)
 
 ENHANCEMENTS:
-* Add Usage Alerts (account): create/get/patch/delete/list; client-side validation; examples.
+* Add Usage Alerts (account): create/get/patch/delete/list; client-side validation; examples. Now accessible via alerts().usage.
 
 ## 0.24.0 (March 20th, 2025)
 

examples/usage_alerts.py

@@ -4,16 +4,10 @@
 #
 
 import os
-import sys
 import json
 from ns1 import NS1
 from ns1.config import Config
 
-# Path hackery to ensure we import the local ns1 module
-sys.path.insert(
-    0, os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
-)
-
 # Create NS1 client
 config = {
     "endpoint": "https://api.nsone.net",
@@ -31,6 +25,11 @@
 c.loadFromDict(config)
 client = NS1(config=c)
 
+# If no real API key is set, we'll get appropriate errors
+# This is just an example to show the usage pattern
+if not os.environ.get("NS1_APIKEY"):
+    print("Using a mock endpoint - for real usage, set the NS1_APIKEY environment variable")
+
 
 # Usage Alerts API Examples
 def usage_alerts_example():
@@ -39,7 +38,7 @@ def usage_alerts_example():
     # List all usage alerts
     print("Listing usage alerts:")
     try:
-        alerts = client.alerting().usage.list(limit=10)
+        alerts = client.alerts().usage.list(limit=10)
         print(f"Total alerts: {alerts.get('total_results', 0)}")
         for i, alert in enumerate(alerts.get("results", [])):
             print(f"  {i+1}. {alert.get('name')} (id: {alert.get('id')})")
@@ -49,7 +48,7 @@ def usage_alerts_example():
     # Create a usage alert
     print("\nCreating a usage alert:")
     try:
-        alert = client.alerting().usage.create(
+        alert = client.alerts().usage.create(
             name="Example query usage alert",
             subtype="query_usage",
             alert_at_percent=85,
@@ -66,7 +65,7 @@ def usage_alerts_example():
     # Update the alert
     print("\nUpdating the alert threshold to 90%:")
     try:
-        updated = client.alerting().usage.patch(alert_id, alert_at_percent=90)
+        updated = client.alerts().usage.patch(alert_id, alert_at_percent=90)
         print(f"Updated alert: {updated['name']}")
         print(f"New threshold: {updated['data']['alert_at_percent']}%")
     except Exception as e:
@@ -75,15 +74,15 @@ def usage_alerts_example():
     # Get alert details
     print("\nGetting alert details:")
     try:
-        details = client.alerting().usage.get(alert_id)
+        details = client.alerts().usage.get(alert_id)
         print(f"Alert details: {json.dumps(details, indent=2)}")
     except Exception as e:
         print(f"Error getting alert: {e}")
 
     # Delete the alert
     print("\nDeleting the alert:")
     try:
-        client.alerting().usage.delete(alert_id)
+        client.alerts().usage.delete(alert_id)
         print(f"Alert {alert_id} deleted successfully")
     except Exception as e:
         print(f"Error deleting alert: {e}")
@@ -96,7 +95,7 @@ def test_validation():
     # Test invalid subtype
     print("Testing invalid subtype:")
     try:
-        client.alerting().usage.create(
+        client.alerts().usage.create(
             name="Test alert", subtype="invalid_subtype", alert_at_percent=85
         )
     except ValueError as e:
@@ -105,7 +104,7 @@ def test_validation():
     # Test threshold too low
     print("\nTesting threshold too low (0):")
     try:
-        client.alerting().usage.create(
+        client.alerts().usage.create(
             name="Test alert", subtype="query_usage", alert_at_percent=0
         )
     except ValueError as e:
@@ -114,7 +113,7 @@ def test_validation():
     # Test threshold too high
     print("\nTesting threshold too high (101):")
     try:
-        client.alerting().usage.create(
+        client.alerts().usage.create(
             name="Test alert", subtype="query_usage", alert_at_percent=101
         )
     except ValueError as e:

ns1/__init__.py

@@ -242,21 +242,6 @@ def alerts(self):
 
         return ns1.rest.alerts.Alerts(self.config)
 
-    def alerting(self):
-        """
-        Return the alerting namespace for accessing alerting features
-
-        :return: Alerting namespace
-        """
-        from ns1.alerting import UsageAlertsAPI
-
-        # Create or reuse the alerting namespace
-        ns = getattr(self, "_alerting_ns", None)
-        if ns is None:
-            ns = type("AlertingNS", (), {})()
-            ns.usage = UsageAlertsAPI(self)
-            setattr(self, "_alerting_ns", ns)
-        return ns
 
     def billing_usage(self):
         """

ns1/alerting/usage_alerts.py

@@ -23,9 +23,14 @@ def _validate(name: str, subtype: str, alert_at_percent: int) -> None:
 
 class UsageAlertsAPI:
     """
-    Account-scoped usage alerts.
-    Server rules: type='account'; data.alert_at_percent in 1..100;
-    PATCH must not include type/subtype; zone_names/notifier_list_ids may be [].
+    Account-scoped usage alerts. Triggers when usage ≥ alert_at_percent.
+    
+    Server rules: 
+    - Always type='account' 
+    - data.alert_at_percent must be in 1..100
+    - PATCH must not include type/subtype
+    - zone_names/notifier_list_ids may be empty ([])
+    - Server ignores datafeed notifiers for usage alerts
     """
 
     def __init__(self, client) -> None:

ns1/rest/alerts.py

@@ -4,6 +4,7 @@
 # License under The MIT License (MIT). See LICENSE in project root.
 #
 from . import resource
+from ns1.alerting import UsageAlertsAPI
 
 
 class Alerts(resource.BaseResource):
@@ -15,6 +16,62 @@ class Alerts(resource.BaseResource):
         "record_ids",
         "zone_names",
     ]
+    
+    # Forward HTTP methods needed by UsageAlertsAPI
+    def _get(self, path, params=None):
+        """Forward GET requests to make_request"""
+        # Fix path to start with /alerting/v1/ if needed
+        if path.startswith('/'):
+            path = path[1:]  # Remove leading slash
+        if not path.startswith("alerting/v1/"):
+            # Alerting endpoints should have this prefix
+            path = f"{self.ROOT}/{path.split('/')[-1]}"
+        return self._make_request("GET", path, params=params)
+    
+    def _post(self, path, json=None):
+        """Forward POST requests to make_request"""
+        if path.startswith('/'):
+            path = path[1:]  # Remove leading slash
+        if not path.startswith("alerting/v1/"):
+            path = f"{self.ROOT}"
+        return self._make_request("POST", path, body=json)
+    
+    def _patch(self, path, json=None):
+        """Forward PATCH requests to make_request"""
+        if path.startswith('/'):
+            path = path[1:]  # Remove leading slash
+        if not path.startswith("alerting/v1/"):
+            parts = path.split('/')
+            path = f"{self.ROOT}/{parts[-1]}"
+        return self._make_request("PATCH", path, body=json)
+        
+    def _delete(self, path):
+        """Forward DELETE requests to make_request"""
+        if path.startswith('/'):
+            path = path[1:]  # Remove leading slash
+        if not path.startswith("alerting/v1/"):
+            parts = path.split('/')
+            path = f"{self.ROOT}/{parts[-1]}"
+        return self._make_request("DELETE", path)
+    
+    def __init__(self, config):
+        super(Alerts, self).__init__(config)
+        self._usage_api = None
+    
+    @property
+    def usage(self):
+        """
+        Return interface to usage alerts operations
+        
+        :return: :py:class:`ns1.alerting.UsageAlertsAPI`
+        """
+        if self._usage_api is None:
+            # The UsageAlertsAPI expects a client with HTTP methods (_get, _post, etc.)
+            # Since the NS1 object is not directly accessible here, we'll use self as the client
+            # The UsageAlertsAPI only needs HTTP methods (_get, _post, etc.)
+            # For tests, we'll later patch the _c attribute on the UsageAlertsAPI instance
+            self._usage_api = UsageAlertsAPI(self)
+        return self._usage_api
 
     def _buildBody(self, alid, **kwargs):
         body = {}

tests/unit/test_usage_alerts.py

@@ -35,7 +35,7 @@ def test_create_usage_alert(usage_alerts_client):
     """Test creating a usage alert"""
     client = usage_alerts_client
 
-    # Create a mock for the _post method in alerting().usage
+    # Create a mock for the _post method
     client._post = mock.MagicMock()
     client._post.return_value = {
         "id": "a1b2c3",
@@ -49,9 +49,12 @@ def test_create_usage_alert(usage_alerts_client):
         "updated_at": 1597937213,
     }
 
-    # Patch the client reference
-    with mock.patch.object(client.alerting().usage, "_c", client):
-        alert = client.alerting().usage.create(
+    # Get the usage API and directly set its client
+    usage_api = client.alerts().usage
+    usage_api._c = client
+    
+    # Make the API call
+    alert = usage_api.create(
             name="Test Alert",
             subtype="query_usage",
             alert_at_percent=85,
@@ -96,9 +99,12 @@ def test_get_usage_alert(usage_alerts_client):
         "zone_names": [],
     }
 
-    # Patch the client reference
-    with mock.patch.object(client.alerting().usage, "_c", client):
-        alert = client.alerting().usage.get(alert_id)
+    # Get the usage API and directly set its client
+    usage_api = client.alerts().usage
+    usage_api._c = client
+    
+    # Make the API call
+    alert = usage_api.get(alert_id)
 
     # Verify _get was called with correct URL
     client._get.assert_called_once_with(f"/alerting/v1/alerts/{alert_id}")
@@ -126,11 +132,14 @@ def test_patch_usage_alert(usage_alerts_client):
         "zone_names": [],
     }
 
-    # Patch the client reference
-    with mock.patch.object(client.alerting().usage, "_c", client):
-        alert = client.alerting().usage.patch(
-            alert_id, name="Updated Alert", alert_at_percent=90
-        )
+    # Get the usage API and directly set its client
+    usage_api = client.alerts().usage
+    usage_api._c = client
+    
+    # Make the API call
+    alert = usage_api.patch(
+        alert_id, name="Updated Alert", alert_at_percent=90
+    )
 
     # Verify _patch was called with correct arguments
     expected_body = {"name": "Updated Alert", "data": {"alert_at_percent": 90}}
@@ -157,9 +166,12 @@ def test_delete_usage_alert(usage_alerts_client):
     # Create a mock for the _delete method
     client._delete = mock.MagicMock()
 
-    # Patch the client reference
-    with mock.patch.object(client.alerting().usage, "_c", client):
-        client.alerting().usage.delete(alert_id)
+    # Get the usage API and directly set its client
+    usage_api = client.alerts().usage
+    usage_api._c = client
+    
+    # Make the API call
+    usage_api.delete(alert_id)
 
     # Verify _delete was called with correct URL
     client._delete.assert_called_once_with(f"/alerting/v1/alerts/{alert_id}")
@@ -186,9 +198,12 @@ def test_list_usage_alerts(usage_alerts_client):
         ],
     }
 
-    # Patch the client reference
-    with mock.patch.object(client.alerting().usage, "_c", client):
-        response = client.alerting().usage.list(limit=1, order_descending=True)
+    # Get the usage API and directly set its client
+    usage_api = client.alerts().usage
+    usage_api._c = client
+    
+    # Make the API call
+    response = usage_api.list(limit=1, order_descending=True)
 
     # Verify _get was called with correct URL and params
     expected_params = {"limit": 1, "order_descending": "true"}
@@ -211,21 +226,21 @@ def test_validation_threshold_bounds(usage_alerts_client):
 
     # Test below minimum
     with pytest.raises(ValueError) as excinfo:
-        client.alerting().usage.create(
+        client.alerts().usage.create(
             name="Test Alert", subtype="query_usage", alert_at_percent=0
         )
     assert "alert_at_percent must be int in 1..100" in str(excinfo.value)
 
     # Test above maximum
     with pytest.raises(ValueError) as excinfo:
-        client.alerting().usage.create(
+        client.alerts().usage.create(
             name="Test Alert", subtype="query_usage", alert_at_percent=101
         )
     assert "alert_at_percent must be int in 1..100" in str(excinfo.value)
 
     # Test same validation in patch
     with pytest.raises(ValueError) as excinfo:
-        client.alerting().usage.patch("a1", alert_at_percent=101)
+        client.alerts().usage.patch("a1", alert_at_percent=101)
     assert "alert_at_percent must be int in 1..100" in str(excinfo.value)