smscode 1.0.0__py3-none-any.whl

smscode/errors.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from typing import Any
+
+
+class SmscodeError(Exception):
+    default_code = "SMSCODE_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        http_status: int | None = None,
+        details: Any | None = None,
+        request_id: str | None = None,
+        retry_after_seconds: float | None = None,
+        idempotency_key: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code or self.default_code
+        self.http_status = http_status
+        self.details = details
+        self.request_id = request_id
+        self.retry_after_seconds = retry_after_seconds
+        self.idempotency_key = idempotency_key
+
+    def with_idempotency_key(self, key: str) -> SmscodeError:
+        if self.idempotency_key is None:
+            self.idempotency_key = key
+        return self
+
+
+class UnauthorizedError(SmscodeError):
+    default_code = "UNAUTHORIZED"
+
+
+class ForbiddenError(SmscodeError):
+    default_code = "FORBIDDEN"
+
+
+class NotFoundError(SmscodeError):
+    default_code = "NOT_FOUND"
+
+
+class ValidationError(SmscodeError):
+    default_code = "VALIDATION_ERROR"
+
+
+class ProviderError(SmscodeError):
+    default_code = "PROVIDER_ERROR"
+
+
+class NoOfferAvailableError(SmscodeError):
+    default_code = "NO_OFFER_AVAILABLE"
+
+
+class IdempotencyKeyReuseError(SmscodeError):
+    default_code = "IDEMPOTENCY_KEY_REUSED"
+
+
+class InsufficientBalanceError(SmscodeError):
+    default_code = "INSUFFICIENT_BALANCE"
+
+
+class ConflictError(SmscodeError):
+    default_code = "CONFLICT"
+
+
+class CancelTooEarlyError(SmscodeError):
+    default_code = "CANCEL_TOO_EARLY"
+
+
+class RequestInProgressError(SmscodeError):
+    default_code = "REQUEST_IN_PROGRESS"
+
+
+class RateLimitError(SmscodeError):
+    default_code = "RATE_LIMIT_EXCEEDED"
+
+
+class TempBannedError(SmscodeError):
+    default_code = "TEMP_BANNED_ABUSE_GUARD"
+
+
+class ServiceUnavailableError(SmscodeError):
+    default_code = "SERVICE_UNAVAILABLE"
+
+
+class FxRateUnavailableError(SmscodeError):
+    default_code = "FX_RATE_UNAVAILABLE"
+
+
+class InternalError(SmscodeError):
+    default_code = "INTERNAL_ERROR"
+
+
+class PayloadTooLargeError(SmscodeError):
+    default_code = "PAYLOAD_TOO_LARGE"
+
+
+class NetworkError(SmscodeError):
+    default_code = "NETWORK_ERROR"
+
+
+class TimeoutError(SmscodeError):
+    default_code = "TIMEOUT"
+
+
+class InvalidResponseError(SmscodeError):
+    default_code = "INVALID_RESPONSE"
+
+
+class InvalidMoneyError(SmscodeError):
+    default_code = "INVALID_MONEY"
+
+
+class OtpTimeoutError(SmscodeError):
+    default_code = "OTP_TIMEOUT"
+
+
+class OrderTerminalError(SmscodeError):
+    default_code = "ORDER_TERMINAL"
+
+
+class RequestCancelledError(asyncio.CancelledError):
+    code = "REQUEST_CANCELLED"
+
+    def __init__(
+        self,
+        message: str = "Request cancelled",
+        *,
+        request_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.http_status: int | None = None
+        self.details: Any | None = None
+        self.request_id = request_id
+        self.retry_after_seconds: float | None = None
+        self.idempotency_key = idempotency_key
+
+    def with_idempotency_key(self, key: str) -> RequestCancelledError:
+        if self.idempotency_key is None:
+            self.idempotency_key = key
+        return self
+
+
+ERROR_BY_CODE: dict[str, type[SmscodeError]] = {
+    "UNAUTHORIZED": UnauthorizedError,
+    "FORBIDDEN": ForbiddenError,
+    "NOT_FOUND": NotFoundError,
+    "VALIDATION_ERROR": ValidationError,
+    "PROVIDER_ERROR": ProviderError,
+    "NO_OFFER_AVAILABLE": NoOfferAvailableError,
+    "IDEMPOTENCY_KEY_REUSED": IdempotencyKeyReuseError,
+    "INSUFFICIENT_BALANCE": InsufficientBalanceError,
+    "CONFLICT": ConflictError,
+    "CANCEL_TOO_EARLY": CancelTooEarlyError,
+    "REQUEST_IN_PROGRESS": RequestInProgressError,
+    "RATE_LIMIT_EXCEEDED": RateLimitError,
+    "TEMP_BANNED_ABUSE_GUARD": TempBannedError,
+    "SERVICE_UNAVAILABLE": ServiceUnavailableError,
+    "FX_RATE_UNAVAILABLE": FxRateUnavailableError,
+    "INTERNAL_ERROR": InternalError,
+    "PAYLOAD_TOO_LARGE": PayloadTooLargeError,
+}
+
+STATUS_FALLBACK: dict[int, tuple[str, type[SmscodeError], str]] = {
+    401: ("UNAUTHORIZED", UnauthorizedError, "Unauthorized"),
+    402: ("INSUFFICIENT_BALANCE", InsufficientBalanceError, "Insufficient balance"),
+    403: ("FORBIDDEN", ForbiddenError, "Forbidden"),
+    404: ("NOT_FOUND", NotFoundError, "Not found"),
+    409: ("CONFLICT", ConflictError, "Conflict"),
+    413: ("PAYLOAD_TOO_LARGE", PayloadTooLargeError, "Payload too large"),
+    422: ("VALIDATION_ERROR", ValidationError, "Validation error"),
+    429: ("RATE_LIMIT_EXCEEDED", RateLimitError, "Rate limit exceeded"),
+    500: ("INTERNAL_ERROR", InternalError, "Internal server error"),
+    503: ("SERVICE_UNAVAILABLE", ServiceUnavailableError, "Service unavailable"),
+}
+
+
+def map_error(
+    *,
+    status: int,
+    payload: Mapping[str, Any] | None,
+    request_id: str | None,
+    retry_after_seconds: float | None,
+) -> SmscodeError:
+    error = payload.get("error") if isinstance(payload, Mapping) else None
+    if isinstance(error, Mapping):
+        code = error.get("code")
+        message = error.get("message")
+        details = error.get("details")
+    else:
+        code = None
+        message = None
+        details = None
+
+    if isinstance(code, str) and code:
+        normalized_code = code
+        error_cls = ERROR_BY_CODE.get(normalized_code, SmscodeError)
+        normalized_message = (
+            message if isinstance(message, str) and message else "SMSCode API error"
+        )
+    else:
+        normalized_code, error_cls, fallback_message = STATUS_FALLBACK.get(
+            status,
+            ("UNKNOWN_ERROR", SmscodeError, "SMSCode API error"),
+        )
+        normalized_message = message if isinstance(message, str) and message else fallback_message
+
+    return error_cls(
+        normalized_message,
+        code=normalized_code,
+        http_status=status,
+        details=details,
+        request_id=request_id,
+        retry_after_seconds=retry_after_seconds,
+    )

smscode/idempotency.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import re
+import uuid
+
+from smscode.errors import ValidationError
+
+IDEMPOTENCY_KEY_PATTERN = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+
+
+def is_valid_idempotency_key(key: str) -> bool:
+    return bool(IDEMPOTENCY_KEY_PATTERN.fullmatch(key))
+
+
+def resolve_idempotency_key(provided: str | None = None) -> str:
+    if provided is not None:
+        if not is_valid_idempotency_key(provided):
+            raise ValidationError(
+                f"Invalid idempotency key {provided!r} (allowed: A-Z a-z 0-9 _ - ; 1-128 chars)."
+            )
+        return provided
+    return str(uuid.uuid4())

smscode/models.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from smscode.errors import InvalidResponseError
+from smscode.money import Money
+
+
+@dataclass(frozen=True)
+class V2Fx:
+    pair: str
+    rate: int | str
+    rate_as_of: str | None = None
+    source: str | None = None
+    as_of: str | None = None
+
+
+@dataclass(frozen=True)
+class ExchangeRate:
+    pair: str
+    rate: int | str
+    base_currency: str | None = None
+    quote_currency: str | None = None
+    rate_as_of: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, compare=False)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.raw.get(key, default)
+
+
+@dataclass(frozen=True)
+class Country:
+    id: int
+    name: str
+    code: str | None = None
+    dial_code: str | None = None
+    emoji: str | None = None
+    active: bool = True
+    raw: dict[str, Any] = field(default_factory=dict, compare=False)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.raw.get(key, default)
+
+
+@dataclass(frozen=True)
+class Service:
+    id: int
+    name: str
+    code: str
+    active: bool = True
+    raw: dict[str, Any] = field(default_factory=dict, compare=False)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.raw.get(key, default)
+
+
+@dataclass(frozen=True)
+class OrderCapabilities:
+    can_finish: bool
+    can_resend: bool
+    can_cancel: bool
+    can_replace: bool
+    resend_available_at: str | None = None
+    cancel_available_at: str | None = None
+    replace_available_at: str | None = None
+
+
+@dataclass(frozen=True)
+class Order:
+    raw: dict[str, Any]
+    capabilities: OrderCapabilities
+    amount: Money | int | None = None
+    fx: V2Fx | None = None
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.raw.get(key, default)
+
+
+@dataclass(frozen=True)
+class CreatedOrder(Order):
+    pass
+
+
+@dataclass(frozen=True)
+class FinishResult:
+    order_id: int
+    status: str
+    raw: dict[str, Any]
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+
+@dataclass(frozen=True)
+class ResendResult:
+    order_id: int
+    status: str
+    raw: dict[str, Any]
+    resent: bool | None = None
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+
+@dataclass(frozen=True)
+class WebhookConfig:
+    webhook_url: str | None
+    webhook_secret: str | None
+    webhook_disabled_at: str | None
+    webhook_disabled_reason: str | None
+    webhook_consecutive_failures: int
+    raw: dict[str, Any]
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+
+@dataclass(frozen=True)
+class WebhookTestResult:
+    status_code: int
+    raw: dict[str, Any]
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    @property
+    def status(self) -> int:
+        return self.status_code
+
+
+@dataclass(frozen=True)
+class BalanceV2:
+    balance: Money
+    fx: V2Fx
+
+
+@dataclass(frozen=True)
+class BalanceV1:
+    balance: int
+    currency: str = "IDR"
+    raw: dict[str, Any] = field(default_factory=dict, compare=False)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.raw.get(key, default)
+
+
+@dataclass(frozen=True)
+class Product:
+    id: int
+    name: str | None
+    country_id: int | None
+    platform_id: int | None
+    available: int
+    price: Money | int | None
+    active: bool
+    catalog_product_id: int | None = None
+    raw: dict[str, Any] = field(default_factory=dict, compare=False)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.raw.get(key, default)
+
+
+@dataclass(frozen=True)
+class ProductV2(Product):
+    price: Money
+
+
+@dataclass(frozen=True)
+class ProductsPage:
+    products: list[Product]
+    page: int | None
+    limit: int | None
+    count: int | None
+    fx: V2Fx | None = None
+
+
+@dataclass(frozen=True)
+class ProductsPageV2(ProductsPage):
+    products: list[Product]
+    page: int | None
+    limit: int | None
+    count: int | None
+    fx: V2Fx
+
+
+@dataclass(frozen=True)
+class ProductsPageV1(ProductsPage):
+    pass
+
+
+@dataclass(frozen=True)
+class OrdersList:
+    orders: list[Order]
+    fx: V2Fx | None = None
+
+
+@dataclass(frozen=True)
+class OrdersListV2(OrdersList):
+    orders: list[Order]
+    fx: V2Fx
+
+
+@dataclass(frozen=True)
+class CreateOrderResult:
+    orders: list[CreatedOrder]
+    failed_count: int
+    idempotency_key: str
+    fx: V2Fx | None = None
+
+
+@dataclass(frozen=True)
+class CreateOrderResultV2(CreateOrderResult):
+    orders: list[CreatedOrder]
+    failed_count: int
+    idempotency_key: str
+    fx: V2Fx
+
+
+@dataclass(frozen=True)
+class CreateOrderResultV1(CreateOrderResult):
+    pass
+
+
+@dataclass(frozen=True)
+class CancelResult:
+    order_id: int
+    status: str
+    refund_amount: Money | int
+    new_balance: Money | int
+    fx: V2Fx | None = None
+
+
+@dataclass(frozen=True)
+class CancelResultV2(CancelResult):
+    order_id: int
+    status: str
+    refund_amount: Money
+    new_balance: Money
+    fx: V2Fx
+
+
+def parse_v2_fx(value: object) -> V2Fx:
+    if not isinstance(value, Mapping):
+        raise InvalidResponseError("The /v2 response is missing its FX receipt.")
+    pair = value.get("pair")
+    rate = value.get("rate")
+    rate_as_of = value.get("rate_as_of")
+    if not isinstance(pair, str) or not isinstance(rate, (int, str)):
+        raise InvalidResponseError("The /v2 response has a malformed FX receipt.")
+    if rate_as_of is not None and not isinstance(rate_as_of, str):
+        raise InvalidResponseError("The /v2 response has a malformed FX receipt.")
+    source = value.get("source")
+    as_of = value.get("as_of")
+    return V2Fx(
+        pair=pair,
+        rate=rate,
+        rate_as_of=rate_as_of,
+        source=source if isinstance(source, str) else None,
+        as_of=as_of if isinstance(as_of, str) else None,
+    )

smscode/money.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+from smscode.errors import InvalidMoneyError
+
+
+@dataclass(frozen=True)
+class Money:
+    amount: str
+    currency: Literal["USD"]
+    canonical_amount: int
+    canonical_currency: Literal["IDR"]
+
+
+def parse_money(value: object) -> Money:
+    if not isinstance(value, Mapping):
+        raise InvalidMoneyError("A money value is missing or malformed in the response.")
+
+    amount = value.get("amount")
+    currency = value.get("currency")
+    canonical_amount = value.get("canonical_amount")
+    canonical_currency = value.get("canonical_currency")
+
+    if (
+        not isinstance(amount, str)
+        or currency != "USD"
+        or type(canonical_amount) is not int
+        or canonical_currency != "IDR"
+    ):
+        raise InvalidMoneyError("A money value is missing or malformed in the response.")
+
+    return Money(
+        amount=amount,
+        currency="USD",
+        canonical_amount=canonical_amount,
+        canonical_currency="IDR",
+    )
+
+
+def parse_optional_money(value: object | None) -> Money | None:
+    if value is None:
+        return None
+    return parse_money(value)

smscode/py.typed

@@ -0,0 +1 @@
+

smscode/resources/__init__.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from smscode.resources.balance import (
+    AsyncV1BalanceResource,
+    AsyncV2BalanceResource,
+    V1BalanceResource,
+    V2BalanceResource,
+)
+from smscode.resources.catalog import (
+    AsyncV1CatalogResource,
+    AsyncV2CatalogResource,
+    V1CatalogResource,
+    V2CatalogResource,
+)
+from smscode.resources.orders import (
+    AsyncV1OrdersResource,
+    AsyncV2OrdersResource,
+    V1OrdersResource,
+    V2OrdersResource,
+)
+from smscode.resources.webhook import (
+    AsyncV1WebhookResource,
+    AsyncV2WebhookResource,
+    V1WebhookResource,
+    V2WebhookResource,
+)
+
+
+@dataclass(frozen=True)
+class V1CatalogBalanceNamespace:
+    catalog: V1CatalogResource
+    balance: V1BalanceResource
+    orders: V1OrdersResource
+    webhook: V1WebhookResource
+
+
+@dataclass(frozen=True)
+class AsyncV1CatalogBalanceNamespace:
+    catalog: AsyncV1CatalogResource
+    balance: AsyncV1BalanceResource
+    orders: AsyncV1OrdersResource
+    webhook: AsyncV1WebhookResource
+
+
+__all__ = [
+    "AsyncV1BalanceResource",
+    "AsyncV1CatalogBalanceNamespace",
+    "AsyncV1CatalogResource",
+    "AsyncV1OrdersResource",
+    "AsyncV1WebhookResource",
+    "AsyncV2BalanceResource",
+    "AsyncV2CatalogResource",
+    "AsyncV2OrdersResource",
+    "AsyncV2WebhookResource",
+    "V1BalanceResource",
+    "V1CatalogBalanceNamespace",
+    "V1CatalogResource",
+    "V1OrdersResource",
+    "V1WebhookResource",
+    "V2BalanceResource",
+    "V2CatalogResource",
+    "V2OrdersResource",
+    "V2WebhookResource",
+]

smscode/resources/balance.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any
+
+from smscode.models import BalanceV1, BalanceV2, parse_v2_fx
+from smscode.money import parse_money
+
+
+def _decode_v2_balance(result: Any) -> BalanceV2:
+    return BalanceV2(balance=parse_money(result.data["balance"]), fx=parse_v2_fx(result.meta["fx"]))
+
+
+def _decode_v1_balance(result: Any) -> BalanceV1:
+    data = result.data
+    currency = data.get("currency") if isinstance(data, dict) else None
+    return BalanceV1(
+        balance=int(data["balance"]),
+        currency=currency if isinstance(currency, str) else "IDR",
+        raw=dict(data),
+    )
+
+
+class V2BalanceResource:
+    def __init__(self, request: Any) -> None:
+        self._request = request
+
+    def get(self) -> BalanceV2:
+        return _decode_v2_balance(self._request("GET", "/v2/balance"))
+
+
+class V1BalanceResource:
+    def __init__(self, request: Any) -> None:
+        self._request = request
+
+    def get(self) -> BalanceV1:
+        return _decode_v1_balance(self._request("GET", "/v1/balance"))
+
+
+class AsyncV2BalanceResource:
+    def __init__(self, request: Any) -> None:
+        self._request = request
+
+    async def get(self) -> BalanceV2:
+        return _decode_v2_balance(await self._request("GET", "/v2/balance"))
+
+
+class AsyncV1BalanceResource:
+    def __init__(self, request: Any) -> None:
+        self._request = request
+
+    async def get(self) -> BalanceV1:
+        return _decode_v1_balance(await self._request("GET", "/v1/balance"))