sendly 3.8.1__py3-none-any.whl

sendly/utils/__init__.py

@@ -0,0 +1,26 @@
+"""Sendly SDK Utilities"""
+
+from .http import AsyncHttpClient, HttpClient
+from .validation import (
+    calculate_segments,
+    get_country_from_phone,
+    is_country_supported,
+    validate_limit,
+    validate_message_id,
+    validate_message_text,
+    validate_phone_number,
+    validate_sender_id,
+)
+
+__all__ = [
+    "HttpClient",
+    "AsyncHttpClient",
+    "validate_phone_number",
+    "validate_message_text",
+    "validate_sender_id",
+    "validate_limit",
+    "validate_message_id",
+    "get_country_from_phone",
+    "is_country_supported",
+    "calculate_segments",
+]

sendly/utils/http.py

@@ -0,0 +1,358 @@
+"""
+HTTP Client Utility
+
+Handles HTTP requests to the Sendly API with retries and rate limiting.
+"""
+
+import asyncio
+import random
+import re
+import time
+from typing import Any, Dict, Optional, TypeVar, Union
+
+import httpx
+
+from ..errors import (
+    NetworkError,
+    RateLimitError,
+    SendlyError,
+    TimeoutError,
+)
+from ..types import RateLimitInfo
+
+T = TypeVar("T")
+
+DEFAULT_BASE_URL = "https://sendly.live/api/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+SDK_VERSION = "1.0.5"
+
+
+class HttpClient:
+    """Synchronous HTTP client for making API requests"""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._rate_limit_info: Optional[RateLimitInfo] = None
+        self._client: Optional[httpx.Client] = None
+
+        # Validate API key format
+        if not self._is_valid_api_key(api_key):
+            raise ValueError("Invalid API key format. Expected sk_test_v1_xxx or sk_live_v1_xxx")
+
+    def _is_valid_api_key(self, key: str) -> bool:
+        """Validate API key format"""
+        return bool(re.match(r"^sk_(test|live)_v1_[a-zA-Z0-9_-]+$", key))
+
+    def is_test_mode(self) -> bool:
+        """Check if using a test API key"""
+        return self.api_key.startswith("sk_test_")
+
+    def get_rate_limit_info(self) -> Optional[RateLimitInfo]:
+        """Get current rate limit info"""
+        return self._rate_limit_info
+
+    @property
+    def client(self) -> httpx.Client:
+        """Get or create the HTTP client"""
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                timeout=self.timeout,
+                headers=self._build_headers(),
+            )
+        return self._client
+
+    def close(self) -> None:
+        """Close the HTTP client"""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def _build_headers(self) -> Dict[str, str]:
+        """Build request headers"""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"sendly-python/{SDK_VERSION}",
+        }
+
+    def _update_rate_limit_info(self, headers: httpx.Headers) -> None:
+        """Update rate limit info from response headers"""
+        limit = headers.get("X-RateLimit-Limit")
+        remaining = headers.get("X-RateLimit-Remaining")
+        reset = headers.get("X-RateLimit-Reset")
+
+        if limit and remaining and reset:
+            self._rate_limit_info = RateLimitInfo(
+                limit=int(limit),
+                remaining=int(remaining),
+                reset=int(reset),
+            )
+
+    def _calculate_backoff(self, attempt: int) -> float:
+        """Calculate exponential backoff time"""
+        base_delay = 2**attempt
+        jitter = random.uniform(0, 0.5)
+        return min(base_delay + jitter, 30.0)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Make an HTTP request to the API"""
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self.client.request(
+                    method=method,
+                    url=path,
+                    json=body,
+                    params=params,
+                )
+
+                # Update rate limit info
+                self._update_rate_limit_info(response.headers)
+
+                # Parse response
+                data = self._parse_response(response)
+                return data
+
+            except SendlyError as e:
+                last_error = e
+
+                # Don't retry certain errors
+                if e.status_code in (400, 401, 402, 403, 404):
+                    raise
+
+                # Handle rate limiting
+                if isinstance(e, RateLimitError):
+                    if attempt < self.max_retries:
+                        time.sleep(e.retry_after)
+                        continue
+                    raise
+
+            except httpx.TimeoutException as e:
+                last_error = TimeoutError(f"Request timed out after {self.timeout}s")
+                if attempt < self.max_retries:
+                    time.sleep(self._calculate_backoff(attempt))
+                    continue
+
+            except httpx.RequestError as e:
+                last_error = NetworkError(f"Network error: {str(e)}", e)
+                if attempt < self.max_retries:
+                    time.sleep(self._calculate_backoff(attempt))
+                    continue
+
+        if last_error:
+            raise last_error
+        raise NetworkError("Request failed after retries")
+
+    def _parse_response(self, response: httpx.Response) -> Any:
+        """Parse the response body"""
+        content_type = response.headers.get("content-type", "")
+
+        if "application/json" in content_type:
+            try:
+                data = response.json()
+            except Exception:
+                data = response.text
+        else:
+            data = response.text
+
+        # Handle error responses
+        if not response.is_success:
+            if isinstance(data, dict):
+                raise SendlyError.from_response(response.status_code, data)
+            raise SendlyError(
+                message=str(data) or f"HTTP {response.status_code}",
+                code="internal_error",
+                status_code=response.status_code,
+            )
+
+        return data
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP client for making API requests"""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._rate_limit_info: Optional[RateLimitInfo] = None
+        self._client: Optional[httpx.AsyncClient] = None
+
+        # Validate API key format
+        if not self._is_valid_api_key(api_key):
+            raise ValueError("Invalid API key format. Expected sk_test_v1_xxx or sk_live_v1_xxx")
+
+    def _is_valid_api_key(self, key: str) -> bool:
+        """Validate API key format"""
+        return bool(re.match(r"^sk_(test|live)_v1_[a-zA-Z0-9_-]+$", key))
+
+    def is_test_mode(self) -> bool:
+        """Check if using a test API key"""
+        return self.api_key.startswith("sk_test_")
+
+    def get_rate_limit_info(self) -> Optional[RateLimitInfo]:
+        """Get current rate limit info"""
+        return self._rate_limit_info
+
+    @property
+    def client(self) -> httpx.AsyncClient:
+        """Get or create the async HTTP client"""
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=self.timeout,
+                headers=self._build_headers(),
+            )
+        return self._client
+
+    async def close(self) -> None:
+        """Close the HTTP client"""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> "AsyncHttpClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    def _build_headers(self) -> Dict[str, str]:
+        """Build request headers"""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"sendly-python/{SDK_VERSION}",
+        }
+
+    def _update_rate_limit_info(self, headers: httpx.Headers) -> None:
+        """Update rate limit info from response headers"""
+        limit = headers.get("X-RateLimit-Limit")
+        remaining = headers.get("X-RateLimit-Remaining")
+        reset = headers.get("X-RateLimit-Reset")
+
+        if limit and remaining and reset:
+            self._rate_limit_info = RateLimitInfo(
+                limit=int(limit),
+                remaining=int(remaining),
+                reset=int(reset),
+            )
+
+    def _calculate_backoff(self, attempt: int) -> float:
+        """Calculate exponential backoff time"""
+        base_delay = 2**attempt
+        jitter = random.uniform(0, 0.5)
+        return min(base_delay + jitter, 30.0)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Make an async HTTP request to the API"""
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self.client.request(
+                    method=method,
+                    url=path,
+                    json=body,
+                    params=params,
+                )
+
+                # Update rate limit info
+                self._update_rate_limit_info(response.headers)
+
+                # Parse response
+                data = self._parse_response(response)
+                return data
+
+            except SendlyError as e:
+                last_error = e
+
+                # Don't retry certain errors
+                if e.status_code in (400, 401, 402, 403, 404):
+                    raise
+
+                # Handle rate limiting
+                if isinstance(e, RateLimitError):
+                    if attempt < self.max_retries:
+                        await asyncio.sleep(e.retry_after)
+                        continue
+                    raise
+
+            except httpx.TimeoutException as e:
+                last_error = TimeoutError(f"Request timed out after {self.timeout}s")
+                if attempt < self.max_retries:
+                    await asyncio.sleep(self._calculate_backoff(attempt))
+                    continue
+
+            except httpx.RequestError as e:
+                last_error = NetworkError(f"Network error: {str(e)}", e)
+                if attempt < self.max_retries:
+                    await asyncio.sleep(self._calculate_backoff(attempt))
+                    continue
+
+        if last_error:
+            raise last_error
+        raise NetworkError("Request failed after retries")
+
+    def _parse_response(self, response: httpx.Response) -> Any:
+        """Parse the response body"""
+        content_type = response.headers.get("content-type", "")
+
+        if "application/json" in content_type:
+            try:
+                data = response.json()
+            except Exception:
+                data = response.text
+        else:
+            data = response.text
+
+        # Handle error responses
+        if not response.is_success:
+            if isinstance(data, dict):
+                raise SendlyError.from_response(response.status_code, data)
+            raise SendlyError(
+                message=str(data) or f"HTTP {response.status_code}",
+                code="internal_error",
+                status_code=response.status_code,
+            )
+
+        return data

sendly/utils/validation.py

@@ -0,0 +1,248 @@
+"""
+Input Validation Utilities
+
+Functions for validating API inputs.
+"""
+
+import re
+from typing import Optional
+
+from ..errors import ValidationError
+from ..types import ALL_SUPPORTED_COUNTRIES
+
+
+def validate_phone_number(phone: str) -> None:
+    """
+    Validate phone number format (E.164)
+
+    Args:
+        phone: Phone number to validate
+
+    Raises:
+        ValidationError: If phone number is invalid
+    """
+    if not phone:
+        raise ValidationError("Phone number is required")
+
+    # E.164 format: + followed by 1-15 digits
+    e164_pattern = r"^\+[1-9]\d{1,14}$"
+
+    if not re.match(e164_pattern, phone):
+        raise ValidationError(
+            f"Invalid phone number format: {phone}. Expected E.164 format (e.g., +15551234567)"
+        )
+
+
+def validate_message_text(text: str) -> None:
+    """
+    Validate message text
+
+    Args:
+        text: Message text to validate
+
+    Raises:
+        ValidationError: If text is invalid
+    """
+    if not text:
+        raise ValidationError("Message text is required")
+
+    if not isinstance(text, str):
+        raise ValidationError("Message text must be a string")
+
+    # Warn about very long messages
+    if len(text) > 1600:
+        import warnings
+
+        warnings.warn(
+            f"Message is {len(text)} characters. "
+            f"This will be split into {calculate_segments(text)} segments."
+        )
+
+
+def validate_sender_id(from_: Optional[str]) -> None:
+    """
+    Validate sender ID
+
+    Args:
+        from_: Sender ID to validate
+
+    Raises:
+        ValidationError: If sender ID is invalid
+    """
+    if not from_:
+        return  # Optional field
+
+    # Phone number format (toll-free)
+    if from_.startswith("+"):
+        validate_phone_number(from_)
+        return
+
+    # Alphanumeric sender ID (2-11 characters)
+    alphanumeric_pattern = r"^[a-zA-Z0-9]{2,11}$"
+
+    if not re.match(alphanumeric_pattern, from_):
+        raise ValidationError(
+            f"Invalid sender ID: {from_}. "
+            "Must be 2-11 alphanumeric characters or a valid phone number."
+        )
+
+
+def validate_limit(limit: Optional[int]) -> None:
+    """
+    Validate list limit
+
+    Args:
+        limit: Limit value to validate
+
+    Raises:
+        ValidationError: If limit is invalid
+    """
+    if limit is None:
+        return
+
+    if not isinstance(limit, int):
+        raise ValidationError("Limit must be an integer")
+
+    if limit < 1 or limit > 100:
+        raise ValidationError("Limit must be between 1 and 100")
+
+
+def validate_message_id(id: str) -> None:
+    """
+    Validate message ID format
+
+    Args:
+        id: Message ID to validate
+
+    Raises:
+        ValidationError: If ID is invalid
+    """
+    if not id:
+        raise ValidationError("Message ID is required")
+
+    if not isinstance(id, str):
+        raise ValidationError("Message ID must be a string")
+
+    # UUID format or prefixed format
+    uuid_pattern = r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    prefixed_pattern = r"^msg_[a-zA-Z0-9_]+$"
+
+    if not (re.match(uuid_pattern, id, re.IGNORECASE) or re.match(prefixed_pattern, id)):
+        raise ValidationError(f"Invalid message ID format: {id}")
+
+
+def get_country_from_phone(phone: str) -> Optional[str]:
+    """
+    Get country code from phone number
+
+    Args:
+        phone: Phone number in E.164 format
+
+    Returns:
+        ISO country code or None if not found
+    """
+    # Remove + prefix
+    digits = phone.lstrip("+")
+
+    # Check US/Canada (country code 1)
+    if digits.startswith("1") and len(digits) == 11:
+        return "US"  # Could be CA, but we treat as domestic
+
+    # Map of country codes to ISO codes
+    country_prefixes = {
+        "44": "GB",
+        "48": "PL",
+        "351": "PT",
+        "40": "RO",
+        "420": "CZ",
+        "36": "HU",
+        "86": "CN",
+        "82": "KR",
+        "91": "IN",
+        "63": "PH",
+        "66": "TH",
+        "84": "VN",
+        "33": "FR",
+        "34": "ES",
+        "46": "SE",
+        "47": "NO",
+        "45": "DK",
+        "358": "FI",
+        "353": "IE",
+        "81": "JP",
+        "61": "AU",
+        "64": "NZ",
+        "65": "SG",
+        "852": "HK",
+        "60": "MY",
+        "62": "ID",
+        "55": "BR",
+        "54": "AR",
+        "56": "CL",
+        "57": "CO",
+        "27": "ZA",
+        "30": "GR",
+        "49": "DE",
+        "39": "IT",
+        "31": "NL",
+        "32": "BE",
+        "43": "AT",
+        "41": "CH",
+        "52": "MX",
+        "972": "IL",
+        "971": "AE",
+        "966": "SA",
+        "20": "EG",
+        "234": "NG",
+        "254": "KE",
+        "886": "TW",
+        "92": "PK",
+        "90": "TR",
+    }
+
+    # Try to match country prefixes (longest first)
+    sorted_prefixes = sorted(country_prefixes.keys(), key=len, reverse=True)
+
+    for prefix in sorted_prefixes:
+        if digits.startswith(prefix):
+            return country_prefixes[prefix]
+
+    return None
+
+
+def is_country_supported(country_code: str) -> bool:
+    """
+    Check if a country is supported
+
+    Args:
+        country_code: ISO country code
+
+    Returns:
+        True if country is supported
+    """
+    return country_code.upper() in ALL_SUPPORTED_COUNTRIES
+
+
+def calculate_segments(text: str) -> int:
+    """
+    Calculate number of SMS segments for a message
+
+    Args:
+        text: Message text
+
+    Returns:
+        Number of SMS segments
+    """
+    # Check if message contains non-GSM characters (requires UCS-2 encoding)
+    # Simple check: any character outside basic ASCII range
+    is_unicode = any(ord(c) > 127 for c in text)
+
+    # GSM: 160 chars single, 153 chars per segment for multi
+    # UCS-2: 70 chars single, 67 chars per segment for multi
+    single_limit = 70 if is_unicode else 160
+    multi_limit = 67 if is_unicode else 153
+
+    if len(text) <= single_limit:
+        return 1
+
+    return (len(text) + multi_limit - 1) // multi_limit