notifox 0.1.2__py3-none-any.whl

notifox/__init__.py

@@ -0,0 +1,18 @@
+from .client import NotifoxClient
+from .exceptions import (
+    NotifoxAPIError,
+    NotifoxAuthenticationError,
+    NotifoxConnectionError,
+    NotifoxError,
+    NotifoxRateLimitError,
+)
+
+__all__ = [
+    "NotifoxClient",
+    "NotifoxError",
+    "NotifoxAPIError",
+    "NotifoxAuthenticationError",
+    "NotifoxRateLimitError",
+    "NotifoxConnectionError",
+]
+__version__ = "0.1.1"

notifox/client.py

@@ -0,0 +1,182 @@
+# notifox/client.py
+import os
+from typing import Any, Dict, Optional
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from .exceptions import (
+    NotifoxAPIError,
+    NotifoxAuthenticationError,
+    NotifoxConnectionError,
+    NotifoxError,
+    NotifoxRateLimitError,
+)
+
+
+class NotifoxClient:
+    """
+    Python SDK for Notifox alerting API.
+
+    Examples:
+        client = NotifoxClient(api_key="your_api_key")
+        client.send_alert(audience="user1", alert="Server down!")
+
+        client = NotifoxClient()  # Reads from NOTIFOX_API_KEY env var
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.notifox.com",
+        timeout: float = 30.0,
+        max_retries: int = 3
+    ):
+        """
+        Initialize the Notifox client.
+
+        Args:
+            api_key: Your Notifox API key. If not provided, will attempt to read from
+                     the NOTIFOX_API_KEY environment variable.
+            base_url: Base URL for the Notifox API. Defaults to https://api.notifox.com
+            timeout: Request timeout in seconds. Defaults to 30.0
+            max_retries: Maximum number of retries for failed requests. Defaults to 3
+        """
+        self.api_key = api_key or os.getenv("NOTIFOX_API_KEY")
+        if not self.api_key:
+            raise NotifoxError(
+                "API key is required. Provide it as an argument or set the "
+                "NOTIFOX_API_KEY environment variable."
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+        # Create a session with retry logic
+        self.session = requests.Session()
+        retry_strategy = Retry(
+            total=max_retries,
+            backoff_factor=0.5,
+            status_forcelist=[429, 500, 502, 503, 504]
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("https://", adapter)
+
+    def _handle_response(self, response: requests.Response) -> Dict[str, Any]:
+        """
+        Handle API response and raise appropriate exceptions for errors.
+
+        Args:
+            response: The HTTP response from the API
+
+        Returns:
+            The JSON response data
+
+        Raises:
+            NotifoxAuthenticationError: For 401 or 403 status codes
+            NotifoxRateLimitError: For 429 status code
+            NotifoxAPIError: For other error status codes
+        """
+        if response.status_code == 401 or response.status_code == 403:
+            raise NotifoxAuthenticationError(
+                f"Authentication failed: {response.status_code}",
+                status_code=response.status_code,
+                response_text=response.text
+            )
+
+        if response.status_code == 429:
+            raise NotifoxRateLimitError(
+                "Rate limit exceeded. Please try again later.",
+                status_code=response.status_code,
+                response_text=response.text
+            )
+
+        if response.status_code >= 400:
+            raise NotifoxAPIError(
+                f"API error: {response.status_code} - {response.text}",
+                status_code=response.status_code,
+                response_text=response.text
+            )
+
+        return response.json()
+
+    def send_alert(
+        self,
+        audience: str,
+        alert: str
+    ) -> Dict[str, Any]:
+        """
+        Sends an alert to the specified audience.
+
+        Args:
+            audience: Audience identifier (e.g., mike, devops, support)
+            alert: The alert message to send
+
+        Returns:
+            API response as a dictionary
+
+        Raises:
+            NotifoxAuthenticationError: If authentication fails
+            NotifoxRateLimitError: If rate limit is exceeded
+            NotifoxAPIError: For other API errors
+            NotifoxConnectionError: If there's a connection issue
+        """
+        url = f"{self.base_url}/alert"
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        payload = {
+            "audience": audience,
+            "alert": alert,
+        }
+
+        try:
+            resp = self.session.post(
+                url,
+                headers=headers,
+                json=payload,
+                timeout=self.timeout
+            )
+            return self._handle_response(resp)
+        except requests.exceptions.Timeout:
+            raise NotifoxConnectionError(
+                f"Request timed out after {self.timeout} seconds"
+            ) from None
+        except requests.exceptions.ConnectionError as e:
+            raise NotifoxConnectionError(f"Connection error: {str(e)}") from e
+        except requests.exceptions.RequestException as e:
+            raise NotifoxError(f"Request failed: {str(e)}") from e
+
+    def calculate_parts(self, alert: str) -> Dict[str, Any]:
+        """
+        Calculates the parts of the alert.
+
+        Args:
+            alert: The alert message to calculate the parts of
+
+        Returns:
+            A dictionary containing information about the alert
+        """
+
+        url = f"{self.base_url}/alert/parts"
+        payload = {
+            "alert": alert
+        }
+
+        try:
+            resp = self.session.post(
+                url,
+                json=payload,
+                timeout=self.timeout
+            )
+
+            return self._handle_response(resp)
+        except requests.exceptions.Timeout:
+            raise NotifoxConnectionError(
+                f"Request timed out after {self.timeout} seconds"
+            ) from None
+        except requests.exceptions.ConnectionError as e:
+            raise NotifoxConnectionError(f"Connection error: {str(e)}") from e
+        except requests.exceptions.RequestException as e:
+            raise NotifoxError(f"Request failed: {str(e)}") from e
+        except Exception as e:
+            raise NotifoxError("An unknown error occurred") from e

notifox/exceptions.py

@@ -0,0 +1,28 @@
+# notifox/exceptions.py
+class NotifoxError(Exception):
+    """Base exception for all Notifox SDK errors."""
+    pass
+
+
+class NotifoxAPIError(NotifoxError):
+    """Raised when the API returns an error response."""
+
+    def __init__(self, message: str, status_code: int, response_text: str = ""):
+        self.status_code = status_code
+        self.response_text = response_text
+        super().__init__(message)
+
+
+class NotifoxAuthenticationError(NotifoxAPIError):
+    """Raised when authentication fails (401/403)."""
+    pass
+
+
+class NotifoxRateLimitError(NotifoxAPIError):
+    """Raised when rate limit is exceeded (429)."""
+    pass
+
+
+class NotifoxConnectionError(NotifoxError):
+    """Raised when there's a connection error to the API."""
+    pass

notifox-0.1.2.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: notifox
+Version: 0.1.2
+Summary: Official Python SDK for Notifox alerting API
+Author: Mathis Van Eetvelde
+License: MIT
+Project-URL: Homepage, https://notifox.com
+Project-URL: Console, https://console.notifox.com
+Project-URL: Docs, https://notifox.com/docs
+Project-URL: API, https://api.notifox.com/
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Dynamic: license-file
+
+# notifox-py
+
+Python SDK for [Notifox](https://notifox.com).
+
+## Installation
+
+```bash
+pip install notifox
+```
+
+## Usage
+
+```python
+from notifox import NotifoxClient
+
+client = NotifoxClient(api_key="your_api_key_here")
+client.send_alert(audience="mike", alert="Database server is down!")
+```
+
+Or use the environment variable:
+
+```bash
+export NOTIFOX_API_KEY="your_api_key_here"
+```
+
+```python
+client = NotifoxClient()  # Reads from NOTIFOX_API_KEY
+client.send_alert(audience="mike", alert="High CPU usage!")
+```
+
+### Configuration
+
+```python
+client = NotifoxClient(
+    api_key="your_api_key",
+    base_url="https://api.notifox.com",
+    timeout=30.0,
+    max_retries=3
+)
+```
+
+## Calculate parts
+
+When you send a message, the length and characters dictate how many parts you will be charged for. You can read more about calculating the parts [here](https://docs.notifox.com/docs/reference/parts).
+
+The Notifox Alerts API exposes a route that lets you calculate the amount of parts a message will be without sending the alert.
+
+```python
+from notifox import NotifoxClient
+
+client = NotifoxClient()
+
+# Calculate the parts of the alert
+response = client.calculate_parts(
+    alert="Hello, world!"
+)
+
+# {'parts': 1, 'cost': 0.025, 'currency': 'USD', 'encoding': 'GSM-7', 'characters': 22, 'message': 'Notifox: Hello, world!'}
+```
+
+## Error Handling
+
+```python
+from notifox import (
+    NotifoxClient,
+    NotifoxAuthenticationError,
+    NotifoxRateLimitError,
+    NotifoxAPIError,
+    NotifoxConnectionError
+)
+
+client = NotifoxClient(api_key="your_api_key")
+
+try:
+    client.send_alert(audience="admin", alert="System is running low on memory")
+except NotifoxAuthenticationError:
+    print("Authentication failed. Check your API key.")
+except NotifoxRateLimitError:
+    print("Rate limit exceeded. Please wait before sending more alerts.")
+except NotifoxAPIError as e:
+    print(f"API error ({e.status_code}): {e.response_text}")
+except NotifoxConnectionError as e:
+    print(f"Connection failed: {e}")
+```
+
+Available exceptions:
+- `NotifoxError` - Base exception
+- `NotifoxAuthenticationError` - Authentication failed (401/403)
+- `NotifoxRateLimitError` - Rate limit exceeded (429)
+- `NotifoxAPIError` - General API errors
+- `NotifoxConnectionError` - Network errors

notifox-0.1.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+notifox/__init__.py,sha256=dvO0GnAfHz9qqs53aecJf-saVHet2XAotFVFPiWCbkY,382
+notifox/client.py,sha256=8F0RfO-id7dWcPzPUedUiwVolKW489YbQqtx6ZKSX7g,5913
+notifox/exceptions.py,sha256=lHDVJrOo5Y-xa0_KyLI2pwPW3yJAlEUpWKDdlpqlnLM,752
+notifox-0.1.2.dist-info/licenses/LICENSE,sha256=eZtQec-wzyeDB7eeTSsosa9_a6RR0ebVBPPxn7xSakQ,1094
+notifox-0.1.2.dist-info/METADATA,sha256=MEGyF38hI7ExSNNS81avYRJzmPT1d2j9bPTteLT74ho,2730
+notifox-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+notifox-0.1.2.dist-info/top_level.txt,sha256=VvmvnNCybE97RLvBOCrYNYCKGdhhVkPBVdYW_kM_spc,8
+notifox-0.1.2.dist-info/RECORD,,

notifox-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

notifox-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Van Eetvelde Ventures LLC DBA Notifox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

notifox-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+notifox