gosms-python 1.0.3__py3-none-any.whl

gosms/__init__.py

@@ -0,0 +1,13 @@
+"""GoSMS.GE Python SDK -- Official SMS gateway client."""
+from gosms.client import SMS
+from gosms.exceptions import GoSmsApiError, GoSmsErrorCode
+
+__version__ = "1.0.3"
+__all__ = ["SMS", "GoSmsApiError", "GoSmsErrorCode"]
+
+try:
+    from gosms.async_client import AsyncSMS  # noqa: F401
+
+    __all__.append("AsyncSMS")
+except ImportError:
+    pass

gosms/_base.py

@@ -0,0 +1,69 @@
+"""Shared base logic for sync and async clients."""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from gosms.exceptions import GoSmsApiError
+
+logger = logging.getLogger("gosms")
+
+
+class _BaseClient:
+    """Base class providing validation, URL building, and error parsing."""
+
+    BASE_URL: str = "https://api.gosms.ge/api"
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        timeout: int = 30,
+        retries: int = 1,
+        debug: bool = False,
+    ) -> None:
+        if not api_key:
+            raise TypeError("api_key is required")
+        if not isinstance(api_key, str):
+            raise TypeError("api_key must be a string")
+
+        self._api_key = api_key
+        self._timeout = timeout
+        self._retries = max(1, retries)
+        self._debug = debug
+
+        if debug:
+            logging.basicConfig(level=logging.DEBUG)
+
+    def _build_url(self, endpoint: str) -> str:
+        return f"{self.BASE_URL}/{endpoint}"
+
+    def _build_payload(self, **kwargs: Any) -> dict[str, Any]:
+        payload: dict[str, Any] = {"api_key": self._api_key}
+        payload.update(kwargs)
+        return payload
+
+    def _parse_response(self, data: dict[str, Any], status_code: int) -> dict[str, Any]:
+        error_code = data.get("errorCode", 0)
+        if status_code >= 400 or error_code:
+            raise GoSmsApiError(
+                error_code=error_code,
+                message=data.get("message", "Unknown error"),
+            )
+        return data
+
+    def _validate_phone_number(self, value: Any, param_name: str) -> None:
+        if not value or not isinstance(value, str):
+            raise TypeError(f"{param_name} is required and must be a string")
+
+    def _validate_string(self, value: Any, param_name: str) -> None:
+        if not value or not isinstance(value, str):
+            raise TypeError(f"{param_name} is required and must be a string")
+
+    def _log(self, *args: Any) -> None:
+        if self._debug:
+            logger.debug("[GOSMS Debug] %s", " ".join(str(a) for a in args))
+
+    def _calculate_delay(self, attempt: int) -> float:
+        """Exponential backoff: 1s, 2s, 4s, ..."""
+        return float(2 ** (attempt - 1))

gosms/async_client.py

@@ -0,0 +1,167 @@
+"""Asynchronous SMS client using the httpx library."""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from gosms._base import _BaseClient
+from gosms.types import (
+    BalanceResponse,
+    CheckStatusResponse,
+    OtpSendResponse,
+    OtpVerifyResponse,
+    SendBulkSmsResponse,
+    SenderCreateResponse,
+    SmsSendResponse,
+)
+
+
+class AsyncSMS(_BaseClient):
+    """Asynchronous GoSMS.GE API client.
+
+    Can be used as an async context manager::
+
+        async with AsyncSMS('api_key') as sms:
+            result = await sms.send('995555123456', 'Hello!', 'GOSMS.GE')
+
+    Or standalone::
+
+        sms = AsyncSMS('api_key')
+        result = await sms.send('995555123456', 'Hello!', 'GOSMS.GE')
+        await sms.close()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        timeout: int = 30,
+        retries: int = 1,
+        debug: bool = False,
+    ) -> None:
+        super().__init__(api_key, timeout=timeout, retries=retries, debug=debug)
+        self._client: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> AsyncSMS:
+        self._client = httpx.AsyncClient(
+            timeout=self._timeout,
+            headers={"Content-Type": "application/json"},
+        )
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=self._timeout,
+                headers={"Content-Type": "application/json"},
+            )
+        return self._client
+
+    async def _make_request(self, endpoint: str, payload: dict[str, Any]) -> dict[str, Any]:
+        url = self._build_url(endpoint)
+        client = self._get_client()
+        last_error: Exception | None = None
+
+        for attempt in range(1, self._retries + 1):
+            try:
+                self._log(f"Request attempt {attempt}/{self._retries} to {endpoint}")
+                response = await client.post(url, json=payload)
+                data: dict[str, Any] = response.json()
+                self._log("Response:", data)
+                return self._parse_response(data, response.status_code)
+            except Exception as exc:
+                last_error = exc
+                self._log(f"Attempt {attempt} failed:", exc)
+                if attempt < self._retries:
+                    delay = self._calculate_delay(attempt)
+                    self._log(f"Retrying in {delay}s...")
+                    await asyncio.sleep(delay)
+
+        raise last_error  # type: ignore[misc]
+
+    async def send(
+        self,
+        phone_number: str,
+        text: str,
+        sender_name: str,
+        urgent: bool = False,
+    ) -> SmsSendResponse:
+        """Send an SMS message to a single recipient."""
+        self._validate_phone_number(phone_number, "phone_number")
+        self._validate_string(text, "text")
+        self._validate_string(sender_name, "sender_name")
+
+        payload = self._build_payload(to=phone_number, text=text, urgent=urgent)
+        payload["from"] = sender_name
+
+        data = await self._make_request("sendsms", payload)
+        return SmsSendResponse.from_dict(data)
+
+    async def send_bulk(
+        self,
+        sender_name: str,
+        phone_numbers: list[str],
+        text: str,
+        urgent: bool = False,
+        no_sms_number: str | None = None,
+    ) -> SendBulkSmsResponse:
+        """Send an SMS message to multiple recipients (max 1000)."""
+        self._validate_string(sender_name, "sender_name")
+        if not isinstance(phone_numbers, list) or len(phone_numbers) == 0:
+            raise TypeError("phone_numbers is required and must be a non-empty list")
+        self._validate_string(text, "text")
+
+        payload = self._build_payload(to=phone_numbers, text=text, urgent=urgent)
+        payload["from"] = sender_name
+        if no_sms_number is not None:
+            payload["noSmsNumber"] = no_sms_number
+
+        data = await self._make_request("sendbulk", payload)
+        return SendBulkSmsResponse.from_dict(data)
+
+    async def send_otp(self, phone_number: str) -> OtpSendResponse:
+        """Send an OTP (One-Time Password) SMS."""
+        self._validate_phone_number(phone_number, "phone_number")
+
+        data = await self._make_request("otp/send", self._build_payload(phone=phone_number))
+        return OtpSendResponse.from_dict(data)
+
+    async def verify_otp(self, phone_number: str, hash: str, code: str) -> OtpVerifyResponse:
+        """Verify an OTP code."""
+        self._validate_phone_number(phone_number, "phone_number")
+        self._validate_string(hash, "hash")
+        self._validate_string(code, "code")
+
+        data = await self._make_request(
+            "otp/verify",
+            self._build_payload(phone=phone_number, hash=hash, code=code),
+        )
+        return OtpVerifyResponse.from_dict(data)
+
+    async def status(self, message_id: int) -> CheckStatusResponse:
+        """Check the delivery status of a sent SMS message."""
+        data = await self._make_request("checksms", self._build_payload(messageId=message_id))
+        return CheckStatusResponse.from_dict(data)
+
+    async def balance(self) -> BalanceResponse:
+        """Check the current SMS balance of your account."""
+        data = await self._make_request("sms-balance", self._build_payload())
+        return BalanceResponse.from_dict(data)
+
+    async def create_sender(self, name: str) -> SenderCreateResponse:
+        """Register a new sender name."""
+        self._validate_string(name, "name")
+
+        data = await self._make_request("sender", self._build_payload(name=name))
+        return SenderCreateResponse.from_dict(data)

gosms/client.py

@@ -0,0 +1,144 @@
+"""Synchronous SMS client using the requests library."""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import requests
+
+from gosms._base import _BaseClient
+from gosms.types import (
+    BalanceResponse,
+    CheckStatusResponse,
+    OtpSendResponse,
+    OtpVerifyResponse,
+    SendBulkSmsResponse,
+    SenderCreateResponse,
+    SmsSendResponse,
+)
+
+
+class SMS(_BaseClient):
+    """Synchronous GoSMS.GE API client.
+
+    Args:
+        api_key: Your API key from https://gosms.ge
+        timeout: Request timeout in seconds (default: 30)
+        retries: Number of retry attempts (default: 1)
+        debug: Enable debug logging (default: False)
+
+    Example::
+
+        sms = SMS('your_api_key')
+        result = sms.send('995555123456', 'Hello!', 'GOSMS.GE')
+        print(result.message_id)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        timeout: int = 30,
+        retries: int = 1,
+        debug: bool = False,
+    ) -> None:
+        super().__init__(api_key, timeout=timeout, retries=retries, debug=debug)
+        self._session = requests.Session()
+        self._session.headers.update({"Content-Type": "application/json"})
+
+    def _make_request(self, endpoint: str, payload: dict[str, Any]) -> dict[str, Any]:
+        url = self._build_url(endpoint)
+        last_error: Exception | None = None
+
+        for attempt in range(1, self._retries + 1):
+            try:
+                self._log(f"Request attempt {attempt}/{self._retries} to {endpoint}")
+                response = self._session.post(url, json=payload, timeout=self._timeout)
+                data: dict[str, Any] = response.json()
+                self._log("Response:", data)
+                return self._parse_response(data, response.status_code)
+            except Exception as exc:
+                last_error = exc
+                self._log(f"Attempt {attempt} failed:", exc)
+                if attempt < self._retries:
+                    delay = self._calculate_delay(attempt)
+                    self._log(f"Retrying in {delay}s...")
+                    time.sleep(delay)
+
+        raise last_error  # type: ignore[misc]
+
+    def send(
+        self,
+        phone_number: str,
+        text: str,
+        sender_name: str,
+        urgent: bool = False,
+    ) -> SmsSendResponse:
+        """Send an SMS message to a single recipient."""
+        self._validate_phone_number(phone_number, "phone_number")
+        self._validate_string(text, "text")
+        self._validate_string(sender_name, "sender_name")
+
+        payload = self._build_payload(to=phone_number, text=text, urgent=urgent)
+        payload["from"] = sender_name
+
+        data = self._make_request("sendsms", payload)
+        return SmsSendResponse.from_dict(data)
+
+    def send_bulk(
+        self,
+        sender_name: str,
+        phone_numbers: list[str],
+        text: str,
+        urgent: bool = False,
+        no_sms_number: str | None = None,
+    ) -> SendBulkSmsResponse:
+        """Send an SMS message to multiple recipients (max 1000)."""
+        self._validate_string(sender_name, "sender_name")
+        if not isinstance(phone_numbers, list) or len(phone_numbers) == 0:
+            raise TypeError("phone_numbers is required and must be a non-empty list")
+        self._validate_string(text, "text")
+
+        payload = self._build_payload(to=phone_numbers, text=text, urgent=urgent)
+        payload["from"] = sender_name
+        if no_sms_number is not None:
+            payload["noSmsNumber"] = no_sms_number
+
+        data = self._make_request("sendbulk", payload)
+        return SendBulkSmsResponse.from_dict(data)
+
+    def send_otp(self, phone_number: str) -> OtpSendResponse:
+        """Send an OTP (One-Time Password) SMS."""
+        self._validate_phone_number(phone_number, "phone_number")
+
+        data = self._make_request("otp/send", self._build_payload(phone=phone_number))
+        return OtpSendResponse.from_dict(data)
+
+    def verify_otp(self, phone_number: str, hash: str, code: str) -> OtpVerifyResponse:
+        """Verify an OTP code."""
+        self._validate_phone_number(phone_number, "phone_number")
+        self._validate_string(hash, "hash")
+        self._validate_string(code, "code")
+
+        data = self._make_request(
+            "otp/verify",
+            self._build_payload(phone=phone_number, hash=hash, code=code),
+        )
+        return OtpVerifyResponse.from_dict(data)
+
+    def status(self, message_id: int) -> CheckStatusResponse:
+        """Check the delivery status of a sent SMS message."""
+        data = self._make_request("checksms", self._build_payload(messageId=message_id))
+        return CheckStatusResponse.from_dict(data)
+
+    def balance(self) -> BalanceResponse:
+        """Check the current SMS balance of your account."""
+        data = self._make_request("sms-balance", self._build_payload())
+        return BalanceResponse.from_dict(data)
+
+    def create_sender(self, name: str) -> SenderCreateResponse:
+        """Register a new sender name."""
+        self._validate_string(name, "name")
+
+        data = self._make_request("sender", self._build_payload(name=name))
+        return SenderCreateResponse.from_dict(data)

gosms/django.py

@@ -0,0 +1,80 @@
+"""Django integration for GoSMS.GE SDK."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from gosms.client import SMS
+
+_client: SMS | None = None
+
+
+class _ImproperlyConfigured(Exception):
+    """Fallback when Django is not installed."""
+
+
+def _get_settings() -> Any:
+    """Import and return Django settings. Separated for testability."""
+    from django.conf import settings
+
+    return settings
+
+
+def _get_improperly_configured() -> type:
+    """Import and return Django's ImproperlyConfigured exception."""
+    try:
+        from django.core.exceptions import ImproperlyConfigured
+
+        return ImproperlyConfigured
+    except ImportError:
+        return _ImproperlyConfigured
+
+
+def get_sms_client(**overrides: Any) -> SMS:
+    """Get or create a singleton SMS client configured from Django settings.
+
+    Reads from ``settings.GOSMS_SETTINGS``::
+
+        # settings.py
+        GOSMS_SETTINGS = {
+            'api_key': 'your_key',
+            'timeout': 30,      # optional
+            'retries': 1,       # optional
+            'debug': False,     # optional (defaults to DEBUG)
+        }
+
+    Usage::
+
+        from gosms.django import get_sms_client
+        sms = get_sms_client()
+        sms.send('995555123456', 'Hello!', 'GOSMS.GE')
+    """
+    global _client
+    if _client is None:
+        from gosms.client import SMS
+
+        settings = _get_settings()
+        ImproperlyConfigured = _get_improperly_configured()
+
+        config: dict[str, Any] = getattr(settings, "GOSMS_SETTINGS", {})
+        api_key = config.get("api_key")
+        if not api_key:
+            raise ImproperlyConfigured(
+                "GOSMS_SETTINGS must contain 'api_key'. "
+                "Add GOSMS_SETTINGS = {'api_key': '...'} to your Django settings."
+            )
+
+        opts: dict[str, Any] = {
+            "timeout": config.get("timeout", 30),
+            "retries": config.get("retries", 1),
+            "debug": config.get("debug", getattr(settings, "DEBUG", False)),
+        }
+        opts.update(overrides)
+        _client = SMS(api_key, **opts)
+    return _client
+
+
+def reset_client() -> None:
+    """Reset the singleton client. Useful for testing."""
+    global _client
+    _client = None

gosms/exceptions.py

@@ -0,0 +1,33 @@
+"""Exception types and error codes for the GoSMS.GE SDK."""
+from __future__ import annotations
+
+
+class GoSmsErrorCode:
+    """Error code constants matching the GoSMS.GE API."""
+
+    INVALID_API_KEY = 100
+    INVALID_SENDER = 101
+    INSUFFICIENT_BALANCE = 102
+    INVALID_PARAMETERS = 103
+    MESSAGE_NOT_FOUND = 104
+    INVALID_PHONE = 105
+    OTP_FAILED = 106
+    SENDER_EXISTS = 107
+    NOT_CONFIGURED = 108
+    TOO_MANY_REQUESTS = 109
+    ACCOUNT_LOCKED = 110
+    OTP_EXPIRED = 111
+    OTP_ALREADY_USED = 112
+    INVALID_NO_SMS_NUMBER = 113
+
+
+class GoSmsApiError(Exception):
+    """Raised when the GoSMS.GE API returns an error response."""
+
+    def __init__(self, error_code: int, message: str) -> None:
+        self.error_code = error_code
+        self.message = message
+        super().__init__(f"[{error_code}] {message}")
+
+    def __repr__(self) -> str:
+        return f"GoSmsApiError(error_code={self.error_code}, message={self.message!r})"

gosms/types.py

@@ -0,0 +1,173 @@
+"""Response type definitions matching the GoSMS.GE API."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SmsSendResponse:
+    success: bool
+    message_id: int
+    sender: str
+    to: str
+    text: str
+    send_at: str
+    balance: int
+    encode: str
+    segment: int
+    sms_characters: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SmsSendResponse:
+        return cls(
+            success=data.get("success", False),
+            message_id=data.get("messageId", 0),
+            sender=data.get("from", ""),
+            to=data.get("to", ""),
+            text=data.get("text", ""),
+            send_at=data.get("sendAt", ""),
+            balance=data.get("balance", 0),
+            encode=data.get("encode", ""),
+            segment=data.get("segment", 0),
+            sms_characters=data.get("smsCharacters", 0),
+        )
+
+
+@dataclass(frozen=True)
+class BulkSmsResult:
+    message_id: int
+    to: str
+    success: bool
+    error: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> BulkSmsResult:
+        return cls(
+            message_id=data.get("messageId", 0),
+            to=data.get("to", ""),
+            success=data.get("success", False),
+            error=data.get("error"),
+        )
+
+
+@dataclass(frozen=True)
+class SendBulkSmsResponse:
+    success: bool
+    total_count: int
+    success_count: int
+    failed_count: int
+    balance: int
+    sender: str
+    text: str
+    encode: str
+    segment: int
+    sms_characters: int
+    messages: list[BulkSmsResult] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SendBulkSmsResponse:
+        return cls(
+            success=data.get("success", False),
+            total_count=data.get("totalCount", 0),
+            success_count=data.get("successCount", 0),
+            failed_count=data.get("failedCount", 0),
+            balance=data.get("balance", 0),
+            sender=data.get("from", ""),
+            text=data.get("text", ""),
+            encode=data.get("encode", ""),
+            segment=data.get("segment", 0),
+            sms_characters=data.get("smsCharacters", 0),
+            messages=[BulkSmsResult.from_dict(m) for m in data.get("messages", [])],
+        )
+
+
+@dataclass(frozen=True)
+class CheckStatusResponse:
+    success: bool
+    message_id: int
+    sender: str
+    to: str
+    text: str
+    send_at: str
+    encode: str
+    segment: int
+    sms_characters: int
+    status: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CheckStatusResponse:
+        return cls(
+            success=data.get("success", False),
+            message_id=data.get("messageId", 0),
+            sender=data.get("from", ""),
+            to=data.get("to", ""),
+            text=data.get("text", ""),
+            send_at=data.get("sendAt", ""),
+            encode=data.get("encode", ""),
+            segment=data.get("segment", 0),
+            sms_characters=data.get("smsCharacters", 0),
+            status=data.get("status", ""),
+        )
+
+
+@dataclass(frozen=True)
+class BalanceResponse:
+    success: bool
+    balance: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> BalanceResponse:
+        return cls(
+            success=data.get("success", False),
+            balance=data.get("balance", 0),
+        )
+
+
+@dataclass(frozen=True)
+class OtpSendResponse:
+    success: bool
+    hash: str
+    balance: int
+    to: str
+    send_at: str
+    encode: str
+    segment: int
+    sms_characters: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> OtpSendResponse:
+        return cls(
+            success=data.get("success", False),
+            hash=data.get("hash", ""),
+            balance=data.get("balance", 0),
+            to=data.get("to", ""),
+            send_at=data.get("sendAt", ""),
+            encode=data.get("encode", ""),
+            segment=data.get("segment", 0),
+            sms_characters=data.get("smsCharacters", 0),
+        )
+
+
+@dataclass(frozen=True)
+class OtpVerifyResponse:
+    success: bool
+    verify: bool
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> OtpVerifyResponse:
+        return cls(
+            success=data.get("success", False),
+            verify=data.get("verify", False),
+        )
+
+
+@dataclass(frozen=True)
+class SenderCreateResponse:
+    success: bool
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SenderCreateResponse:
+        return cls(
+            success=data.get("success", False),
+        )

gosms_python-1.0.3.dist-info/METADATA

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: gosms-python
+Version: 1.0.3
+Summary: Official Python SDK for GoSMS.GE SMS Gateway
+Project-URL: Homepage, https://gosms.ge
+Project-URL: Repository, https://github.com/gosms-ge/gosmsge-python
+Project-URL: Issues, https://github.com/gosms-ge/gosmsge-python/issues
+Author-email: "GoSMS.GE" <info@gosms.ge>
+License-Expression: MIT
+Keywords: gosms,otp,sms,sms-api,sms-gateway,sms-sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28.0
+Provides-Extra: async
+Requires-Dist: httpx>=0.24.0; extra == 'async'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == 'django'
+Description-Content-Type: text/markdown
+
+# GoSMS.GE Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/gosms-python.svg)](https://pypi.org/project/gosms-python/)
+[![Python versions](https://img.shields.io/pypi/pyversions/gosms-python.svg)](https://pypi.org/project/gosms-python/)
+[![Tests](https://github.com/gosms-python/gosms-python-python/actions/workflows/release.yml/badge.svg)](https://github.com/gosms-python/gosms-python-python/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Official Python SDK for the [GoSMS.GE](https://gosms.ge) SMS gateway. Send SMS messages, manage OTP verification, and check balances with both sync and async clients.
+
+## Installation
+
+```bash
+pip install gosms-python
+```
+
+For async support:
+
+```bash
+pip install gosms-python[async]
+```
+
+## Quick Start
+
+```python
+from gosms import SMS
+
+sms = SMS("your_api_key")
+
+# Send a message
+result = sms.send("995555123456", "Hello!", "GOSMS.GE")
+print(result.message_id)  # 12345
+print(result.balance)     # 99
+
+# Check balance
+balance = sms.balance()
+print(balance.balance)  # 500
+```
+
+## All Endpoints
+
+### Send SMS
+
+```python
+result = sms.send("995555123456", "Hello!", "GOSMS.GE")
+result = sms.send("995555123456", "Urgent!", "GOSMS.GE", urgent=True)
+```
+
+### Send Bulk SMS
+
+```python
+result = sms.send_bulk(
+    "GOSMS.GE",
+    ["995555111111", "995555222222"],
+    "Hello everyone!",
+)
+print(result.total_count)    # 2
+print(result.success_count)  # 2
+
+for msg in result.messages:
+    print(f"{msg.to}: {msg.message_id}")
+```
+
+### Send OTP
+
+```python
+result = sms.send_otp("995555123456")
+print(result.hash)  # "abc123hash" — save this for verification
+```
+
+### Verify OTP
+
+```python
+result = sms.verify_otp("995555123456", "abc123hash", "1234")
+print(result.verify)  # True
+```
+
+### Check Message Status
+
+```python
+result = sms.status(12345)
+print(result.status)  # "delivered"
+```
+
+### Check Balance
+
+```python
+result = sms.balance()
+print(result.balance)  # 500
+```
+
+### Create Sender Name
+
+```python
+result = sms.create_sender("MyBrand")
+print(result.success)  # True
+```
+
+## Async Usage
+
+```python
+import asyncio
+from gosms import AsyncSMS
+
+async def main():
+    async with AsyncSMS("your_api_key") as sms:
+        result = await sms.send("995555123456", "Hello!", "GOSMS.GE")
+        print(result.message_id)
+
+        balance = await sms.balance()
+        print(balance.balance)
+
+asyncio.run(main())
+```
+
+All methods from the sync client are available as async equivalents with the same signatures.
+
+## Django Integration
+
+Add to your `settings.py`:
+
+```python
+GOSMS_SETTINGS = {
+    "api_key": "your_api_key",
+    "timeout": 30,    # optional
+    "retries": 1,     # optional
+}
+```
+
+Use anywhere in your project:
+
+```python
+from gosms.django import get_sms_client
+
+sms = get_sms_client()
+sms.send("995555123456", "Hello!", "GOSMS.GE")
+```
+
+The client is created lazily on first call and reused as a singleton.
+
+## Configuration
+
+```python
+sms = SMS(
+    "your_api_key",
+    timeout=30,   # request timeout in seconds (default: 30)
+    retries=3,    # retry attempts on failure (default: 1)
+    debug=True,   # enable debug logging (default: False)
+)
+```
+
+## Error Handling
+
+```python
+from gosms import SMS, GoSmsApiError, GoSmsErrorCode
+
+sms = SMS("your_api_key")
+
+try:
+    result = sms.send("995555123456", "Hello!", "GOSMS.GE")
+except GoSmsApiError as e:
+    print(e.error_code)  # 100
+    print(e.message)     # "Invalid API key"
+
+    if e.error_code == GoSmsErrorCode.INVALID_API_KEY:
+        print("Check your API key")
+```
+
+### Error Codes
+
+| Code | Constant | Description |
+|------|----------|-------------|
+| 100 | `INVALID_API_KEY` | Invalid API key |
+| 101 | `INVALID_PHONE_NUMBER` | Invalid phone number |
+| 102 | `INSUFFICIENT_BALANCE` | Insufficient balance |
+| 103 | `SENDER_NOT_FOUND` | Sender name not found |
+| 104 | `INVALID_TEXT` | Invalid message text |
+| 105 | `TOO_MANY_RECIPIENTS` | Too many recipients (max 1000) |
+| 106 | `INVALID_MESSAGE_ID` | Invalid message ID |
+| 107 | `SENDER_EXISTS` | Sender name already exists |
+| 108 | `INVALID_SENDER_NAME` | Invalid sender name |
+| 109 | `INVALID_OTP_HASH` | Invalid OTP hash |
+| 110 | `INVALID_OTP_CODE` | Invalid OTP code |
+| 111 | `OTP_EXPIRED` | OTP expired |
+| 112 | `OTP_ALREADY_VERIFIED` | OTP already verified |
+| 113 | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded |
+
+## Response Types
+
+All methods return typed frozen dataclasses:
+
+| Method | Return Type | Key Fields |
+|--------|-------------|------------|
+| `send()` | `SmsSendResponse` | `success`, `message_id`, `balance` |
+| `send_bulk()` | `SendBulkSmsResponse` | `success`, `total_count`, `messages` |
+| `send_otp()` | `OtpSendResponse` | `success`, `hash`, `balance` |
+| `verify_otp()` | `OtpVerifyResponse` | `success`, `verify` |
+| `status()` | `CheckStatusResponse` | `success`, `status`, `message_id` |
+| `balance()` | `BalanceResponse` | `success`, `balance` |
+| `create_sender()` | `SenderCreateResponse` | `success` |
+
+## Migration from v1.x
+
+v2.0 is a complete rewrite. Key changes:
+
+```python
+# v1.x (old)
+from gosms import sms                    # module-level singleton
+sms.send('995...', 'text', 'SENDER')
+
+# v2.0 (new)
+from gosms import SMS                    # explicit instantiation
+sms = SMS('your_api_key')
+sms.send('995...', 'text', 'SENDER')
+
+# v1.x Django (old)
+from gosms import sms                    # import-time side effect
+
+# v2.0 Django (new)
+from gosms.django import get_sms_client  # lazy factory
+sms = get_sms_client()
+```
+
+Other changes:
+- `GoSmsApiError` now extends `Exception` (was `BaseException`)
+- Added `GoSmsErrorCode` constants for typed error handling
+- Added `send_bulk()` and `create_sender()` endpoints
+- Added async client (`AsyncSMS`) via `pip install gosms-python[async]`
+- All responses are typed frozen dataclasses
+- Removed `dev_mode` / `RequestMock` in favor of standard test mocking
+
+## License
+
+MIT
+
+## Links
+
+- Website: https://gosms.ge
+- PyPI: https://pypi.org/project/gosms-python/
+- GitHub: https://github.com/gosms-python/gosms-python-python
+- Support: info@gosms.ge

gosms_python-1.0.3.dist-info/RECORD

@@ -0,0 +1,11 @@
+gosms/__init__.py,sha256=MtJSvCMP5rqx_Yi-Fzw9bJ7cXtwHV9In_4OJXcHs5z0,347
+gosms/_base.py,sha256=mRtlZ-iMxGouswbVwNZvJulbzLB5AYF0_34Lh7A7nMQ,2210
+gosms/async_client.py,sha256=OSZEyGFcSAiEvLttQNM4WhzF8GwSqB2GM3iS6d5Hixs,5924
+gosms/client.py,sha256=5u0F-wUpy2eItn8X7IYF-h7WHMoEV8omfTbvSqTpGTI,5175
+gosms/django.py,sha256=R8__y8LbWTcv2zgtOVwRcUnzjqT5B_faj3u3yZpCwLs,2246
+gosms/exceptions.py,sha256=fpUslXvA3oNFb4eixbJ5s5tJgM4ew_-7FymKBz0dYGs,951
+gosms/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gosms/types.py,sha256=9Lu13z3DRUqODb_gu0nFivRd7cX0JKCq6ZFk4oVP1r4,4580
+gosms_python-1.0.3.dist-info/METADATA,sha256=odYFHrYQgRgmeiRR-u7s3LwMlkUU8Qkhkhd4sOJxyF8,7533
+gosms_python-1.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+gosms_python-1.0.3.dist-info/RECORD,,

gosms_python-1.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any