sendly 3.8.1__py3-none-any.whl

sendly/__init__.py

@@ -0,0 +1,165 @@
+"""
+Sendly Python SDK
+
+Official SDK for the Sendly SMS API.
+
+Example:
+    >>> from sendly import Sendly
+    >>>
+    >>> client = Sendly('sk_live_v1_your_api_key')
+    >>>
+    >>> # Send an SMS
+    >>> message = client.messages.send(
+    ...     to='+15551234567',
+    ...     text='Hello from Sendly!'
+    ... )
+    >>> print(f'Message sent: {message.id}')
+
+Async Example:
+    >>> import asyncio
+    >>> from sendly import AsyncSendly
+    >>>
+    >>> async def main():
+    ...     async with AsyncSendly('sk_live_v1_xxx') as client:
+    ...         message = await client.messages.send(
+    ...             to='+15551234567',
+    ...             text='Hello!'
+    ...         )
+    >>>
+    >>> asyncio.run(main())
+"""
+
+__version__ = "1.0.5"
+
+# Main clients
+from .client import AsyncSendly, Sendly
+
+# Errors
+from .errors import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    SendlyError,
+    TimeoutError,
+    ValidationError,
+)
+
+# Types
+from .types import (
+    ALL_SUPPORTED_COUNTRIES,
+    # Constants
+    CREDITS_PER_SMS,
+    SANDBOX_TEST_NUMBERS,
+    SUPPORTED_COUNTRIES,
+    # Account types
+    Account,
+    ApiKey,
+    CircuitState,
+    CreateWebhookOptions,
+    Credits,
+    CreditTransaction,
+    DeliveryStatus,
+    ListMessagesOptions,
+    Message,
+    MessageListResponse,
+    MessageStatus,
+    PricingTier,
+    RateLimitInfo,
+    SandboxTestNumbers,
+    SenderType,
+    SendlyConfig,
+    SendMessageRequest,
+    TransactionType,
+    UpdateWebhookOptions,
+    # Webhook types
+    Webhook,
+    WebhookCreatedResponse,
+    WebhookDelivery,
+    WebhookSecretRotation,
+    WebhookTestResult,
+)
+
+# Utilities (for advanced usage)
+from .utils.validation import (
+    calculate_segments,
+    get_country_from_phone,
+    is_country_supported,
+    validate_message_text,
+    validate_phone_number,
+    validate_sender_id,
+)
+
+# Webhooks
+from .webhooks import (
+    WebhookEvent,
+    WebhookEventType,
+    WebhookMessageData,
+    WebhookMessageStatus,
+    Webhooks,
+    WebhookSignatureError,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Clients
+    "Sendly",
+    "AsyncSendly",
+    # Types
+    "SendlyConfig",
+    "SendMessageRequest",
+    "Message",
+    "MessageStatus",
+    "SenderType",
+    "ListMessagesOptions",
+    "MessageListResponse",
+    "RateLimitInfo",
+    "PricingTier",
+    # Webhook types
+    "Webhook",
+    "WebhookCreatedResponse",
+    "CreateWebhookOptions",
+    "UpdateWebhookOptions",
+    "WebhookDelivery",
+    "WebhookTestResult",
+    "WebhookSecretRotation",
+    "CircuitState",
+    "DeliveryStatus",
+    # Account types
+    "Account",
+    "Credits",
+    "CreditTransaction",
+    "TransactionType",
+    "ApiKey",
+    # Constants
+    "CREDITS_PER_SMS",
+    "SUPPORTED_COUNTRIES",
+    "ALL_SUPPORTED_COUNTRIES",
+    "SANDBOX_TEST_NUMBERS",
+    "SandboxTestNumbers",
+    # Errors
+    "SendlyError",
+    "AuthenticationError",
+    "RateLimitError",
+    "InsufficientCreditsError",
+    "ValidationError",
+    "NotFoundError",
+    "NetworkError",
+    "TimeoutError",
+    # Utilities
+    "validate_phone_number",
+    "validate_message_text",
+    "validate_sender_id",
+    "get_country_from_phone",
+    "is_country_supported",
+    "calculate_segments",
+    # Webhooks
+    "Webhooks",
+    "WebhookSignatureError",
+    "WebhookEvent",
+    "WebhookEventType",
+    "WebhookMessageData",
+    "WebhookMessageStatus",
+]

sendly/client.py

@@ -0,0 +1,248 @@
+"""
+Sendly Client
+
+Main entry point for the Sendly SDK.
+"""
+
+from typing import Any, Optional, Union
+
+from .resources.account import AccountResource, AsyncAccountResource
+from .resources.messages import AsyncMessagesResource, MessagesResource
+from .resources.webhooks import AsyncWebhooksResource, WebhooksResource
+from .types import RateLimitInfo, SendlyConfig
+from .utils.http import AsyncHttpClient, HttpClient
+
+DEFAULT_BASE_URL = "https://sendly.live/api/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+
+
+class Sendly:
+    """
+    Sendly API Client (synchronous)
+
+    The main entry point for interacting with the Sendly SMS API.
+
+    Example:
+        >>> from sendly import Sendly
+        >>>
+        >>> # Initialize with API key
+        >>> client = Sendly('sk_live_v1_your_api_key')
+        >>>
+        >>> # Send an SMS
+        >>> message = client.messages.send(
+        ...     to='+15551234567',
+        ...     text='Hello from Sendly!'
+        ... )
+        >>> print(message.id)
+
+    Example with configuration:
+        >>> client = Sendly(
+        ...     api_key='sk_live_v1_your_api_key',
+        ...     timeout=60.0,
+        ...     max_retries=5
+        ... )
+
+    Example with context manager:
+        >>> with Sendly('sk_live_v1_xxx') as client:
+        ...     message = client.messages.send(to='+1555...', text='Hello!')
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        config: Optional[SendlyConfig] = None,
+    ):
+        """
+        Create a new Sendly client
+
+        Args:
+            api_key: Your Sendly API key (sk_test_v1_xxx or sk_live_v1_xxx)
+            base_url: Base URL for the API (default: https://sendly.live/api/v1)
+            timeout: Request timeout in seconds (default: 30)
+            max_retries: Maximum retry attempts (default: 3)
+            config: Alternative configuration object
+        """
+        # Handle configuration
+        if config is not None:
+            api_key = config.api_key
+            base_url = config.base_url
+            timeout = config.timeout
+            max_retries = config.max_retries
+        elif api_key is None:
+            raise ValueError("api_key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+        # Initialize HTTP client
+        self._http = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        # Initialize resources
+        self.messages = MessagesResource(self._http)
+        self.webhooks = WebhooksResource(self._http)
+        self.account = AccountResource(self._http)
+
+    def __enter__(self) -> "Sendly":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources"""
+        self._http.close()
+
+    def is_test_mode(self) -> bool:
+        """
+        Check if the client is using a test API key
+
+        Returns:
+            True if using a test key (sk_test_v1_xxx)
+
+        Example:
+            >>> if client.is_test_mode():
+            ...     print('Running in test mode')
+        """
+        return self._http.is_test_mode()
+
+    def get_rate_limit_info(self) -> Optional[RateLimitInfo]:
+        """
+        Get current rate limit information
+
+        Returns the rate limit info from the most recent API request.
+
+        Returns:
+            Rate limit info or None if no requests have been made
+
+        Example:
+            >>> client.messages.send(to='+1555...', text='Hello!')
+            >>> rate_limit = client.get_rate_limit_info()
+            >>> if rate_limit:
+            ...     print(f'{rate_limit.remaining}/{rate_limit.limit} remaining')
+        """
+        return self._http.get_rate_limit_info()
+
+    @property
+    def base_url(self) -> str:
+        """Get the configured base URL"""
+        return self._base_url
+
+
+class AsyncSendly:
+    """
+    Sendly API Client (asynchronous)
+
+    Async version of the Sendly client for use with asyncio.
+
+    Example:
+        >>> import asyncio
+        >>> from sendly import AsyncSendly
+        >>>
+        >>> async def main():
+        ...     async with AsyncSendly('sk_live_v1_xxx') as client:
+        ...         message = await client.messages.send(
+        ...             to='+15551234567',
+        ...             text='Hello from Sendly!'
+        ...         )
+        ...         print(message.id)
+        >>>
+        >>> asyncio.run(main())
+
+    Example without context manager:
+        >>> client = AsyncSendly('sk_live_v1_xxx')
+        >>> try:
+        ...     message = await client.messages.send(to='+1555...', text='Hello!')
+        ... finally:
+        ...     await client.close()
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        config: Optional[SendlyConfig] = None,
+    ):
+        """
+        Create a new async Sendly client
+
+        Args:
+            api_key: Your Sendly API key (sk_test_v1_xxx or sk_live_v1_xxx)
+            base_url: Base URL for the API (default: https://sendly.live/api/v1)
+            timeout: Request timeout in seconds (default: 30)
+            max_retries: Maximum retry attempts (default: 3)
+            config: Alternative configuration object
+        """
+        # Handle configuration
+        if config is not None:
+            api_key = config.api_key
+            base_url = config.base_url
+            timeout = config.timeout
+            max_retries = config.max_retries
+        elif api_key is None:
+            raise ValueError("api_key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+        # Initialize HTTP client
+        self._http = AsyncHttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        # Initialize resources
+        self.messages = AsyncMessagesResource(self._http)
+        self.webhooks = AsyncWebhooksResource(self._http)
+        self.account = AsyncAccountResource(self._http)
+
+    async def __aenter__(self) -> "AsyncSendly":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the HTTP client and release resources"""
+        await self._http.close()
+
+    def is_test_mode(self) -> bool:
+        """
+        Check if the client is using a test API key
+
+        Returns:
+            True if using a test key (sk_test_v1_xxx)
+        """
+        return self._http.is_test_mode()
+
+    def get_rate_limit_info(self) -> Optional[RateLimitInfo]:
+        """
+        Get current rate limit information
+
+        Returns:
+            Rate limit info or None if no requests have been made
+        """
+        return self._http.get_rate_limit_info()
+
+    @property
+    def base_url(self) -> str:
+        """Get the configured base URL"""
+        return self._base_url

sendly/errors.py

@@ -0,0 +1,169 @@
+"""
+Sendly SDK Error Classes
+
+Custom exceptions for different error scenarios.
+"""
+
+from typing import Any, Dict, Optional
+
+from .types import ApiErrorResponse
+
+
+class SendlyError(Exception):
+    """Base error class for all Sendly SDK errors"""
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "internal_error",
+        status_code: Optional[int] = None,
+        response: Optional[ApiErrorResponse] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.response = response
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[{self.code}] ({self.status_code}) {self.message}"
+        return f"[{self.code}] {self.message}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(code={self.code!r}, message={self.message!r})"
+
+    @classmethod
+    def from_response(cls, status_code: int, response_data: Dict[str, Any]) -> "SendlyError":
+        """Create a SendlyError from an API response"""
+        try:
+            error_response = ApiErrorResponse(**response_data)
+        except Exception:
+            error_response = ApiErrorResponse(
+                error="internal_error",
+                message=str(response_data),
+            )
+
+        code = error_response.error
+        message = error_response.message
+
+        # Return specific error types based on error code
+        if code in (
+            "unauthorized",
+            "invalid_auth_format",
+            "invalid_key_format",
+            "invalid_api_key",
+            "api_key_required",
+            "key_revoked",
+            "key_expired",
+            "insufficient_permissions",
+        ):
+            return AuthenticationError(message, code, status_code, error_response)
+
+        if code == "rate_limit_exceeded":
+            return RateLimitError(
+                message,
+                retry_after=error_response.retry_after or 60,
+                status_code=status_code,
+                response=error_response,
+            )
+
+        if code == "insufficient_credits":
+            return InsufficientCreditsError(
+                message,
+                credits_needed=error_response.credits_needed or 0,
+                current_balance=error_response.current_balance or 0,
+                status_code=status_code,
+                response=error_response,
+            )
+
+        if code in ("invalid_request", "unsupported_destination"):
+            return ValidationError(message, code, status_code, error_response)
+
+        if code == "not_found":
+            return NotFoundError(message, status_code, error_response)
+
+        return cls(message, code, status_code, error_response)
+
+
+class AuthenticationError(SendlyError):
+    """Thrown when authentication fails"""
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "unauthorized",
+        status_code: Optional[int] = None,
+        response: Optional[ApiErrorResponse] = None,
+    ):
+        super().__init__(message, code, status_code, response)
+
+
+class RateLimitError(SendlyError):
+    """Thrown when rate limit is exceeded"""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: int,
+        status_code: Optional[int] = None,
+        response: Optional[ApiErrorResponse] = None,
+    ):
+        super().__init__(message, "rate_limit_exceeded", status_code, response)
+        self.retry_after = retry_after
+
+
+class InsufficientCreditsError(SendlyError):
+    """Thrown when credit balance is insufficient"""
+
+    def __init__(
+        self,
+        message: str,
+        credits_needed: int,
+        current_balance: int,
+        status_code: Optional[int] = None,
+        response: Optional[ApiErrorResponse] = None,
+    ):
+        super().__init__(message, "insufficient_credits", status_code, response)
+        self.credits_needed = credits_needed
+        self.current_balance = current_balance
+
+
+class ValidationError(SendlyError):
+    """Thrown when request validation fails"""
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "invalid_request",
+        status_code: Optional[int] = None,
+        response: Optional[ApiErrorResponse] = None,
+    ):
+        super().__init__(message, code, status_code, response)
+
+
+class NotFoundError(SendlyError):
+    """Thrown when a resource is not found"""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response: Optional[ApiErrorResponse] = None,
+    ):
+        super().__init__(message, "not_found", status_code, response)
+
+
+class NetworkError(SendlyError):
+    """Thrown when a network or connection error occurs"""
+
+    def __init__(self, message: str, cause: Optional[Exception] = None):
+        super().__init__(message, "internal_error")
+        self.cause = cause
+
+
+class TimeoutError(SendlyError):
+    """Thrown when a request times out"""
+
+    def __init__(self, message: str = "Request timed out"):
+        super().__init__(message, "internal_error")

sendly/resources/__init__.py

@@ -0,0 +1,5 @@
+"""Sendly SDK Resources"""
+
+from .messages import AsyncMessagesResource, MessagesResource
+
+__all__ = ["MessagesResource", "AsyncMessagesResource"]