smscode 1.0.0__py3-none-any.whl

smscode/__init__.py

@@ -0,0 +1,153 @@
+from importlib import metadata
+
+from smscode.async_client import AsyncSmscodeClient
+from smscode.client import SmscodeClient
+from smscode.errors import (
+    CancelTooEarlyError,
+    ConflictError,
+    ForbiddenError,
+    FxRateUnavailableError,
+    IdempotencyKeyReuseError,
+    InsufficientBalanceError,
+    InternalError,
+    InvalidMoneyError,
+    InvalidResponseError,
+    NetworkError,
+    NoOfferAvailableError,
+    NotFoundError,
+    OrderTerminalError,
+    OtpTimeoutError,
+    PayloadTooLargeError,
+    ProviderError,
+    RateLimitError,
+    RequestCancelledError,
+    RequestInProgressError,
+    ServiceUnavailableError,
+    SmscodeError,
+    TempBannedError,
+    TimeoutError,
+    UnauthorizedError,
+    ValidationError,
+    map_error,
+)
+from smscode.idempotency import (
+    IDEMPOTENCY_KEY_PATTERN,
+    is_valid_idempotency_key,
+    resolve_idempotency_key,
+)
+from smscode.models import (
+    BalanceV1,
+    BalanceV2,
+    CancelResult,
+    CancelResultV2,
+    Country,
+    CreatedOrder,
+    CreateOrderResult,
+    CreateOrderResultV1,
+    CreateOrderResultV2,
+    ExchangeRate,
+    FinishResult,
+    Order,
+    OrderCapabilities,
+    OrdersList,
+    OrdersListV2,
+    Product,
+    ProductsPage,
+    ProductsPageV1,
+    ProductsPageV2,
+    ProductV2,
+    ResendResult,
+    Service,
+    V2Fx,
+    WebhookConfig,
+    WebhookTestResult,
+)
+from smscode.money import Money, parse_money
+from smscode.retry import RetryPolicy, async_with_retry, with_retry
+from smscode.types import ApiResult, RequestOptions
+from smscode.wait import OtpResult, async_wait_for_otp, wait_for_otp
+from smscode.webhook import (
+    WebhookEvent,
+    is_webhook_event,
+    parse_webhook_event,
+    verify_webhook_signature,
+)
+
+VERSION = metadata.version("smscode")
+__version__ = VERSION
+
+
+__all__ = [
+    "IDEMPOTENCY_KEY_PATTERN",
+    "VERSION",
+    "ApiResult",
+    "AsyncSmscodeClient",
+    "BalanceV1",
+    "BalanceV2",
+    "CancelResult",
+    "CancelResultV2",
+    "CancelTooEarlyError",
+    "ConflictError",
+    "Country",
+    "CreateOrderResult",
+    "CreateOrderResultV1",
+    "CreateOrderResultV2",
+    "CreatedOrder",
+    "ExchangeRate",
+    "FinishResult",
+    "ForbiddenError",
+    "FxRateUnavailableError",
+    "IdempotencyKeyReuseError",
+    "InsufficientBalanceError",
+    "InternalError",
+    "InvalidMoneyError",
+    "InvalidResponseError",
+    "Money",
+    "NetworkError",
+    "NoOfferAvailableError",
+    "NotFoundError",
+    "Order",
+    "OrderCapabilities",
+    "OrderTerminalError",
+    "OrdersList",
+    "OrdersListV2",
+    "OtpResult",
+    "OtpTimeoutError",
+    "PayloadTooLargeError",
+    "Product",
+    "ProductV2",
+    "ProductsPage",
+    "ProductsPageV1",
+    "ProductsPageV2",
+    "ProviderError",
+    "RateLimitError",
+    "RequestCancelledError",
+    "RequestInProgressError",
+    "RequestOptions",
+    "ResendResult",
+    "RetryPolicy",
+    "Service",
+    "ServiceUnavailableError",
+    "SmscodeClient",
+    "SmscodeError",
+    "TempBannedError",
+    "TimeoutError",
+    "UnauthorizedError",
+    "V2Fx",
+    "ValidationError",
+    "WebhookConfig",
+    "WebhookEvent",
+    "WebhookTestResult",
+    "__version__",
+    "async_wait_for_otp",
+    "async_with_retry",
+    "is_valid_idempotency_key",
+    "is_webhook_event",
+    "map_error",
+    "parse_money",
+    "parse_webhook_event",
+    "resolve_idempotency_key",
+    "verify_webhook_signature",
+    "wait_for_otp",
+    "with_retry",
+]

smscode/_async_transport.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from smscode._decode import decode_response, retry_after_from_error
+from smscode._transport import DEFAULT_BASE_URL, build_url, clean_params, is_retryable
+from smscode.errors import NetworkError, TimeoutError
+from smscode.retry import RetryPolicy, async_with_retry
+from smscode.types import ApiResult, HttpMethod, QueryValue
+
+
+class AsyncTransport:
+    def __init__(
+        self,
+        *,
+        token: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_ms: int = 0,
+        max_retries: int = 0,
+        client: httpx.AsyncClient | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not token:
+            raise TypeError("AsyncSmscodeClient requires a token.")
+        if client is not None and transport is not None:
+            raise TypeError("Pass either client or transport, not both.")
+        self._token = token
+        self._base_url = base_url
+        self._max_retries = max(0, max_retries)
+        self._owns_client = client is None
+        timeout = None if timeout_ms <= 0 else timeout_ms / 1000
+        self._client = client or httpx.AsyncClient(timeout=timeout, transport=transport)
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def request(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: Mapping[str, QueryValue] | None = None,
+        json: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        retry: int | None = None,
+    ) -> ApiResult[Any]:
+        max_retries = self._max_retries if retry is None else max(0, retry)
+        policy = RetryPolicy(
+            max_retries=max_retries,
+            retry_on=is_retryable,
+            retry_after=retry_after_from_error,
+        )
+        return await async_with_retry(
+            lambda: self._attempt(method, path, params=params, json=json, headers=headers),
+            policy,
+        )
+
+    async def _attempt(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: Mapping[str, QueryValue] | None,
+        json: Any | None,
+        headers: Mapping[str, str] | None,
+    ) -> ApiResult[Any]:
+        request_headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if headers is not None:
+            request_headers.update(headers)
+        try:
+            response = await self._client.request(
+                method,
+                build_url(self._base_url, path),
+                params=clean_params(params),
+                json=json,
+                headers=request_headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(str(exc) or "SMSCode request timed out") from exc
+        except httpx.RequestError as exc:
+            raise NetworkError(str(exc) or "SMSCode network request failed") from exc
+        return decode_response(response)

smscode/_decode.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import timezone
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+import httpx
+
+from smscode.errors import SmscodeError, map_error
+from smscode.types import ApiResult
+
+
+def retry_after_seconds(headers: httpx.Headers) -> float | None:
+    value = headers.get("Retry-After")
+    if value is None:
+        return None
+    try:
+        seconds = float(value)
+    except ValueError:
+        try:
+            retry_at = parsedate_to_datetime(value)
+        except (TypeError, ValueError):
+            return None
+        if retry_at.tzinfo is None:
+            retry_at = retry_at.replace(tzinfo=timezone.utc)
+        date_header = headers.get("Date")
+        if date_header is None:
+            return None
+        try:
+            response_date = parsedate_to_datetime(date_header)
+        except (TypeError, ValueError):
+            return None
+        if response_date.tzinfo is None:
+            response_date = response_date.replace(tzinfo=timezone.utc)
+        return max(0.0, (retry_at - response_date).total_seconds())
+    return max(0.0, seconds)
+
+
+def retry_after_from_error(err: Exception) -> float | None:
+    if isinstance(err, SmscodeError):
+        return err.retry_after_seconds
+    return None
+
+
+def decode_response(response: httpx.Response) -> ApiResult[Any]:
+    request_id = response.headers.get("X-Request-Id")
+    payload = _json_or_none(response)
+    envelope = payload if isinstance(payload, Mapping) else None
+    is_failure = not response.is_success or (
+        envelope is not None and envelope.get("success") is False
+    )
+    if is_failure:
+        raise map_error(
+            status=response.status_code,
+            payload=envelope,
+            request_id=request_id,
+            retry_after_seconds=retry_after_seconds(response.headers),
+        )
+
+    meta_value = envelope.get("meta") if envelope is not None else None
+    meta = dict(meta_value) if isinstance(meta_value, Mapping) else None
+    data = envelope.get("data") if envelope is not None and "data" in envelope else payload
+    return ApiResult(data=data, meta=meta, request_id=request_id, status=response.status_code)
+
+
+def _json_or_none(response: httpx.Response) -> object | None:
+    if not response.content:
+        return None
+    try:
+        parsed: object = response.json()
+        return parsed
+    except ValueError:
+        return None

smscode/_transport.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from smscode._decode import decode_response, retry_after_from_error
+from smscode.errors import NetworkError, SmscodeError, TimeoutError
+from smscode.retry import RetryPolicy, with_retry
+from smscode.types import ApiResult, HttpMethod, QueryValue
+
+DEFAULT_BASE_URL = "https://api.smscode.gg"
+RETRYABLE_STATUSES = {429, 503}
+
+
+def build_url(base_url: str, path: str) -> str:
+    base = base_url.rstrip("/")
+    rel = path if path.startswith("/") else f"/{path}"
+    return f"{base}{rel}"
+
+
+def clean_params(params: Mapping[str, QueryValue] | None) -> dict[str, str] | None:
+    if params is None:
+        return None
+    cleaned: dict[str, str] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        cleaned[key] = str(value).lower() if isinstance(value, bool) else str(value)
+    return cleaned
+
+
+class SyncTransport:
+    def __init__(
+        self,
+        *,
+        token: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_ms: int = 0,
+        max_retries: int = 0,
+        client: httpx.Client | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not token:
+            raise TypeError("SmscodeClient requires a token.")
+        if client is not None and transport is not None:
+            raise TypeError("Pass either client or transport, not both.")
+        self._token = token
+        self._base_url = base_url
+        self._max_retries = max(0, max_retries)
+        self._owns_client = client is None
+        timeout = None if timeout_ms <= 0 else timeout_ms / 1000
+        self._client = client or httpx.Client(timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def request(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: Mapping[str, QueryValue] | None = None,
+        json: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        retry: int | None = None,
+    ) -> ApiResult[Any]:
+        max_retries = self._max_retries if retry is None else max(0, retry)
+        policy = RetryPolicy(
+            max_retries=max_retries,
+            retry_on=is_retryable,
+            retry_after=retry_after_from_error,
+        )
+        return with_retry(
+            lambda: self._attempt(method, path, params=params, json=json, headers=headers),
+            policy,
+        )
+
+    def _attempt(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: Mapping[str, QueryValue] | None,
+        json: Any | None,
+        headers: Mapping[str, str] | None,
+    ) -> ApiResult[Any]:
+        request_headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if headers is not None:
+            request_headers.update(headers)
+        try:
+            response = self._client.request(
+                method,
+                build_url(self._base_url, path),
+                params=clean_params(params),
+                json=json,
+                headers=request_headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(str(exc) or "SMSCode request timed out") from exc
+        except httpx.RequestError as exc:
+            raise NetworkError(str(exc) or "SMSCode network request failed") from exc
+        return decode_response(response)
+
+
+def is_retryable(err: Exception) -> bool:
+    if isinstance(err, NetworkError):
+        return True
+    return isinstance(err, SmscodeError) and err.http_status in RETRYABLE_STATUSES

smscode/async_client.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from smscode._async_transport import AsyncTransport
+from smscode._transport import DEFAULT_BASE_URL
+from smscode.resources import (
+    AsyncV1CatalogBalanceNamespace,
+    AsyncV1CatalogResource,
+    AsyncV2CatalogResource,
+)
+from smscode.resources.balance import AsyncV1BalanceResource, AsyncV2BalanceResource
+from smscode.resources.orders import AsyncV1OrdersResource, AsyncV2OrdersResource
+from smscode.resources.webhook import AsyncV1WebhookResource, AsyncV2WebhookResource
+from smscode.types import ApiResult, HttpMethod, QueryValue
+
+
+class AsyncSmscodeClient:
+    def __init__(
+        self,
+        *,
+        token: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_ms: int = 0,
+        max_retries: int = 0,
+        client: httpx.AsyncClient | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._transport = AsyncTransport(
+            token=token,
+            base_url=base_url,
+            timeout_ms=timeout_ms,
+            max_retries=max_retries,
+            client=client,
+            transport=transport,
+        )
+        self.catalog = AsyncV2CatalogResource(self.request)
+        self.balance = AsyncV2BalanceResource(self.request)
+        self.orders = AsyncV2OrdersResource(self.request)
+        self.webhook = AsyncV2WebhookResource(self.request)
+        self.v1 = AsyncV1CatalogBalanceNamespace(
+            catalog=AsyncV1CatalogResource(self.request),
+            balance=AsyncV1BalanceResource(self.request),
+            orders=AsyncV1OrdersResource(self.request),
+            webhook=AsyncV1WebhookResource(self.request),
+        )
+
+    async def __aenter__(self) -> AsyncSmscodeClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def request(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: Mapping[str, QueryValue] | None = None,
+        json: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        retry: int | None = None,
+    ) -> ApiResult[Any]:
+        return await self._transport.request(
+            method,
+            path,
+            params=params,
+            json=json,
+            headers=headers,
+            retry=retry,
+        )

smscode/client.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from smscode._transport import DEFAULT_BASE_URL, SyncTransport
+from smscode.resources import V1CatalogBalanceNamespace, V1CatalogResource, V2CatalogResource
+from smscode.resources.balance import V1BalanceResource, V2BalanceResource
+from smscode.resources.orders import V1OrdersResource, V2OrdersResource
+from smscode.resources.webhook import V1WebhookResource, V2WebhookResource
+from smscode.types import ApiResult, HttpMethod, QueryValue
+
+
+class SmscodeClient:
+    def __init__(
+        self,
+        *,
+        token: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_ms: int = 0,
+        max_retries: int = 0,
+        client: httpx.Client | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._transport = SyncTransport(
+            token=token,
+            base_url=base_url,
+            timeout_ms=timeout_ms,
+            max_retries=max_retries,
+            client=client,
+            transport=transport,
+        )
+        self.catalog = V2CatalogResource(self.request)
+        self.balance = V2BalanceResource(self.request)
+        self.orders = V2OrdersResource(self.request)
+        self.webhook = V2WebhookResource(self.request)
+        self.v1 = V1CatalogBalanceNamespace(
+            catalog=V1CatalogResource(self.request),
+            balance=V1BalanceResource(self.request),
+            orders=V1OrdersResource(self.request),
+            webhook=V1WebhookResource(self.request),
+        )
+
+    def __enter__(self) -> SmscodeClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def request(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: Mapping[str, QueryValue] | None = None,
+        json: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        retry: int | None = None,
+    ) -> ApiResult[Any]:
+        return self._transport.request(
+            method,
+            path,
+            params=params,
+            json=json,
+            headers=headers,
+            retry=retry,
+        )