eveses 0.1.0__py3-none-any.whl

eveses/__init__.py

@@ -0,0 +1,66 @@
+"""
+eveses — Official Python SDK.
+
+Quickstart:
+
+    from eveses import Eveses
+    client = Eveses(api_key="sk_…")
+    order = client.activations.create(country="ua", service="telegram")
+    wallet = client.wallet.balance()
+    services = client.catalog.services(mode="activation", country="ua")
+
+Webhook verification:
+
+    from eveses import Webhooks
+    ok = Webhooks.verify(raw_body, signature_header, secret, timestamp=ts_header)
+"""
+
+from .activations import Activations, Order, OrderSms, OrderSmsBundle
+from .catalog import (
+    Catalog,
+    CatalogCountriesResponse,
+    CatalogPricingDuration,
+    CatalogPricingResponse,
+    CatalogServiceWithDurations,
+    CatalogServicesResponse,
+)
+from .client import Eveses
+from .exceptions import (
+    EvesesAuthError,
+    EvesesError,
+    EvesesForbiddenError,
+    EvesesNotFoundError,
+    EvesesRateLimitError,
+    EvesesServerError,
+    EvesesValidationError,
+)
+from .wallet import Wallet, WalletBalance
+from .webhooks import Webhooks, verify_webhook
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Eveses",
+    "Activations",
+    "Catalog",
+    "Wallet",
+    "Webhooks",
+    "verify_webhook",
+    "Order",
+    "OrderSms",
+    "OrderSmsBundle",
+    "WalletBalance",
+    "CatalogCountriesResponse",
+    "CatalogServicesResponse",
+    "CatalogPricingResponse",
+    "CatalogServiceWithDurations",
+    "CatalogPricingDuration",
+    "EvesesError",
+    "EvesesAuthError",
+    "EvesesForbiddenError",
+    "EvesesNotFoundError",
+    "EvesesValidationError",
+    "EvesesRateLimitError",
+    "EvesesServerError",
+    "__version__",
+]

eveses/activations.py

@@ -0,0 +1,157 @@
+"""
+Activations / orders namespace.
+
+Note: the public OpenAPI spec exposes orders under `/api/account/orders/*`.
+There is no dedicated `/api/v1/activations` route today; for API-key
+consumers (kind=api_key Sanctum tokens), v1 is a thin wrapper around the
+account-scoped controllers. This module hits the account-scoped paths.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .client import Eveses
+
+
+@dataclass
+class Order:
+    order_id: str
+    status: str
+    phone: Optional[str] = None
+    country: Optional[str] = None
+    service: Optional[str] = None
+    mode: Optional[str] = None
+    price_cents: Optional[int] = None
+    expires_at: Optional[str] = None
+    created_at: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class OrderSms:
+    id: int
+    text: str
+    sender: Optional[str] = None
+    received_at: Optional[str] = None
+
+
+@dataclass
+class OrderSmsBundle:
+    order_id: str
+    stored: List[OrderSms]
+    fresh: List[OrderSms]
+
+
+class Activations:
+    """Wrapper around `/api/account/orders/*`."""
+
+    def __init__(self, client: "Eveses") -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        country: str,
+        service: str,
+        mode: str = "activation",
+        duration_minutes: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+        max_price_cents: Optional[int] = None,
+    ) -> Order:
+        """Provision a number for a country/service. Returns the created order."""
+        body: Dict[str, Any] = {"mode": mode, "country": country, "service": service}
+        if duration_minutes is not None:
+            body["duration_minutes"] = duration_minutes
+        if idempotency_key is not None:
+            body["idempotency_key"] = idempotency_key
+        if max_price_cents is not None:
+            body["max_price_cents"] = max_price_cents
+
+        headers: Dict[str, str] = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        res = self._client.request(
+            "POST",
+            "/api/account/orders",
+            json_body=body,
+            headers=headers,
+        )
+        return _map_order(_unwrap(res))
+
+    def get(self, order_id: str) -> Order:
+        res = self._client.request("GET", f"/api/account/orders/{_quote(order_id)}")
+        return _map_order(_unwrap(res))
+
+    def cancel(self, order_id: str) -> Order:
+        """Release the number and refund the user (where supported)."""
+        res = self._client.request("POST", f"/api/account/orders/{_quote(order_id)}/cancel")
+        return _map_order(_unwrap(res))
+
+    def finish(self, order_id: str) -> Order:
+        """Mark the order completed once the SMS has been consumed."""
+        res = self._client.request("POST", f"/api/account/orders/{_quote(order_id)}/finish")
+        return _map_order(_unwrap(res))
+
+    def sms(self, order_id: str) -> OrderSmsBundle:
+        """
+        Get all SMS messages for an order. Combines `stored` (delivered to us
+        via webhook) with `fresh` (pulled from the upstream provider on demand).
+        """
+        res = self._client.request("GET", f"/api/account/orders/{_quote(order_id)}/sms")
+        data = _unwrap(res)
+        return OrderSmsBundle(
+            order_id=str(data.get("order_id") or order_id),
+            stored=[_map_sms(m) for m in (data.get("stored") or [])],
+            fresh=[_map_sms(m) for m in (data.get("fresh") or [])],
+        )
+
+
+# --------------------------------------------------------------- internals --
+def _unwrap(payload: Any) -> Dict[str, Any]:
+    if isinstance(payload, dict) and isinstance(payload.get("data"), dict):
+        return payload["data"]
+    if isinstance(payload, dict):
+        return payload
+    return {}
+
+
+def _map_order(d: Dict[str, Any]) -> Order:
+    return Order(
+        order_id=str(d.get("order_id") or ""),
+        status=str(d.get("status") or "pending"),
+        phone=_str_or_none(d.get("phone")),
+        country=_str_or_none(d.get("country")),
+        service=_str_or_none(d.get("service")),
+        mode=_str_or_none(d.get("mode")),
+        price_cents=_int_or_none(d.get("price_cents")),
+        expires_at=_str_or_none(d.get("expires_at")),
+        created_at=_str_or_none(d.get("created_at")),
+        raw=dict(d),
+    )
+
+
+def _map_sms(m: Dict[str, Any]) -> OrderSms:
+    return OrderSms(
+        id=int(m.get("id") or 0),
+        text=str(m.get("text") or ""),
+        sender=_str_or_none(m.get("sender")),
+        received_at=_str_or_none(m.get("received_at")),
+    )
+
+
+def _str_or_none(v: Any) -> Optional[str]:
+    return v if isinstance(v, str) else None
+
+
+def _int_or_none(v: Any) -> Optional[int]:
+    return v if isinstance(v, int) else None
+
+
+def _quote(value: str) -> str:
+    from urllib.parse import quote
+
+    return quote(value, safe="")

eveses/catalog.py

@@ -0,0 +1,216 @@
+"""
+Catalog namespace — read-only metadata used to drive the UX before
+creating an order: which countries / services are available, and how
+much each combination costs.
+
+Targets the API-key-authenticated v1 routes:
+
+    GET /api/v1/numbers/countries?mode=
+    GET /api/v1/numbers/products?mode=     (the "services" list)
+    GET /api/v1/numbers/pricing?mode=&country=&product=&duration=
+
+Wire-shape note: the v1 list endpoint is named `products` for legacy
+reasons — it returns the same flat string list the rest of the SDK
+calls "services". The pricing endpoint takes `product=` on the wire,
+which we accept here under the friendlier `service` name.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .client import Eveses
+
+
+@dataclass
+class CatalogCountriesResponse:
+    mode: str
+    countries: List[str] = field(default_factory=list)
+
+
+@dataclass
+class CatalogServicesResponse:
+    mode: str
+    services: List[str] = field(default_factory=list)
+    country: Optional[str] = None
+    currency: Optional[str] = None
+
+
+@dataclass
+class CatalogPricingDuration:
+    duration_minutes: int
+    price_cents: Optional[int] = None
+    price: Optional[float] = None
+    currency: Optional[str] = None
+    available: Optional[bool] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class CatalogServiceWithDurations:
+    name: str
+    durations: List[CatalogPricingDuration] = field(default_factory=list)
+
+
+@dataclass
+class CatalogPricingResponse:
+    mode: str
+    country: str
+    services: List[CatalogServiceWithDurations] = field(default_factory=list)
+    currency: Optional[str] = None
+    service: Optional[str] = None
+
+
+class Catalog:
+    """Wrapper around `/api/v1/numbers/{countries,products,pricing}`."""
+
+    def __init__(self, client: "Eveses") -> None:
+        self._client = client
+
+    def countries(self, *, mode: str = "activation") -> CatalogCountriesResponse:
+        """List ISO-3166-1 alpha-2 country codes that have stock for ``mode``."""
+        res = self._client.request(
+            "GET",
+            "/api/v1/numbers/countries",
+            params={"mode": mode},
+        )
+        d = _unwrap(res)
+        countries_raw = d.get("countries") or []
+        countries = [str(c) for c in countries_raw] if isinstance(countries_raw, list) else []
+        return CatalogCountriesResponse(
+            mode=str(d.get("mode") or mode),
+            countries=countries,
+        )
+
+    def services(
+        self,
+        *,
+        mode: str = "activation",
+        country: Optional[str] = None,
+        currency: Optional[str] = None,
+    ) -> CatalogServicesResponse:
+        """
+        List service / product codes available globally for ``mode``.
+
+        ``country`` and ``currency`` are accepted for symmetry with the
+        broader catalog API but are currently informational on the v1
+        endpoint, which returns the unified product list.
+        """
+        res = self._client.request(
+            "GET",
+            "/api/v1/numbers/products",
+            params={"mode": mode},
+        )
+        d = _unwrap(res)
+        products_raw = d.get("products") or []
+        services = [str(p) for p in products_raw] if isinstance(products_raw, list) else []
+        return CatalogServicesResponse(
+            mode=str(d.get("mode") or mode),
+            services=services,
+            country=country.lower() if isinstance(country, str) and country else None,
+            currency=currency.upper() if isinstance(currency, str) and currency else None,
+        )
+
+    def pricing(
+        self,
+        *,
+        country: str,
+        service: str,
+        mode: str = "activation",
+        currency: Optional[str] = None,
+        duration_minutes: Optional[int] = None,
+    ) -> CatalogPricingResponse:
+        """Fetch pricing for a country/service pair (optionally for a specific duration)."""
+        if not country:
+            raise ValueError("country is required")
+        if not service:
+            raise ValueError("service is required")
+
+        params: Dict[str, Any] = {
+            "mode": mode,
+            "country": country.lower(),
+            "product": service,
+        }
+        if currency:
+            params["currency"] = currency.upper()
+        if duration_minutes is not None:
+            params["duration"] = duration_minutes
+
+        res = self._client.request(
+            "GET",
+            "/api/v1/numbers/pricing",
+            params=params,
+        )
+        d = _unwrap(res)
+
+        services_raw = d.get("services") or []
+        services: List[CatalogServiceWithDurations] = []
+        if isinstance(services_raw, list):
+            for entry in services_raw:
+                services.append(_map_service_entry(entry))
+
+        return CatalogPricingResponse(
+            mode=str(d.get("mode") or mode),
+            country=str(d.get("country") or country.lower()),
+            currency=_str_or_none(d.get("currency")) or (currency.upper() if currency else None),
+            service=service,
+            services=services,
+        )
+
+
+# --------------------------------------------------------------- internals --
+def _unwrap(payload: Any) -> Dict[str, Any]:
+    if isinstance(payload, dict) and isinstance(payload.get("data"), dict):
+        return payload["data"]
+    if isinstance(payload, dict):
+        return payload
+    return {}
+
+
+def _map_service_entry(entry: Any) -> CatalogServiceWithDurations:
+    if not isinstance(entry, dict):
+        return CatalogServiceWithDurations(name="", durations=[])
+    durations_raw = entry.get("durations") or []
+    durations: List[CatalogPricingDuration] = []
+    if isinstance(durations_raw, list):
+        for d in durations_raw:
+            durations.append(_map_duration(d))
+    return CatalogServiceWithDurations(
+        name=str(entry.get("name") or ""),
+        durations=durations,
+    )
+
+
+def _map_duration(d: Any) -> CatalogPricingDuration:
+    if not isinstance(d, dict):
+        return CatalogPricingDuration(duration_minutes=0)
+    available = d.get("available")
+    if not isinstance(available, bool):
+        in_stock = d.get("in_stock")
+        available = in_stock if isinstance(in_stock, bool) else None
+    return CatalogPricingDuration(
+        duration_minutes=int(d.get("duration_minutes") or 0),
+        price_cents=_int_or_none(d.get("price_cents")),
+        price=_float_or_none(d.get("price")),
+        currency=_str_or_none(d.get("currency")),
+        available=available,
+        raw=dict(d),
+    )
+
+
+def _str_or_none(v: Any) -> Optional[str]:
+    return v if isinstance(v, str) else None
+
+
+def _int_or_none(v: Any) -> Optional[int]:
+    return v if isinstance(v, int) and not isinstance(v, bool) else None
+
+
+def _float_or_none(v: Any) -> Optional[float]:
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    return None

eveses/client.py

@@ -0,0 +1,198 @@
+"""
+Eveses client. Hand-rolled wrapper around `requests` with:
+  - Bearer auth header
+  - JSON serialisation
+  - Idempotency-Key header passthrough
+  - One automatic retry on 429 (using Retry-After if present)
+  - Typed exceptions for non-2xx responses
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Dict, Mapping, Optional
+
+import requests
+
+from .exceptions import (
+    EvesesAuthError,
+    EvesesError,
+    EvesesForbiddenError,
+    EvesesNotFoundError,
+    EvesesRateLimitError,
+    EvesesServerError,
+    EvesesValidationError,
+)
+
+DEFAULT_BASE_URL = "https://api.eveses.io"
+DEFAULT_TIMEOUT_S = 30.0
+DEFAULT_USER_AGENT = "eveses-python/0.1.0"
+
+
+class Eveses:
+    """
+    Top-level SDK client.
+
+    Example:
+        from eveses import Eveses
+        client = Eveses(api_key=os.environ["EVESES_API_KEY"])
+        order = client.activations.create(country="ua", service="telegram")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_S,
+        session: Optional[requests.Session] = None,
+        default_headers: Optional[Mapping[str, str]] = None,
+        user_agent: str = DEFAULT_USER_AGENT,
+    ) -> None:
+        if not api_key:
+            raise EvesesError("api_key is required", 0)
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.user_agent = user_agent
+        self._session = session or requests.Session()
+        self._default_headers = dict(default_headers or {})
+
+        # Lazy import to avoid circular references at module-import time.
+        from .activations import Activations
+        from .catalog import Catalog
+        from .wallet import Wallet
+        from .webhooks import Webhooks
+
+        self.activations = Activations(self)
+        self.wallet = Wallet(self)
+        self.catalog = Catalog(self)
+        # Static-like helper. Also importable as `from eveses import Webhooks`.
+        self.webhooks = Webhooks
+
+    # -------------------------------------------------------------- request --
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json_body: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        """Send a single authenticated request and return parsed JSON."""
+        url = self._build_url(path)
+        merged_headers: Dict[str, str] = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        merged_headers.update(self._default_headers)
+        if headers:
+            merged_headers.update(headers)
+        if json_body is not None:
+            merged_headers.setdefault("Content-Type", "application/json")
+
+        body_str: Optional[str] = None
+        if json_body is not None:
+            body_str = json.dumps(json_body, separators=(",", ":"))
+
+        return self._execute_with_retry(method, url, merged_headers, params, body_str)
+
+    def _execute_with_retry(
+        self,
+        method: str,
+        url: str,
+        headers: Dict[str, str],
+        params: Optional[Mapping[str, Any]],
+        body: Optional[str],
+        attempt: int = 0,
+    ) -> Any:
+        try:
+            response = self._session.request(
+                method=method,
+                url=url,
+                headers=headers,
+                params=_clean_params(params),
+                data=body,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise EvesesError(f"Network error: {exc}", 0) from exc
+
+        if response.status_code == 429 and attempt == 0:
+            time.sleep(_parse_retry_after(response.headers.get("Retry-After")))
+            return self._execute_with_retry(method, url, headers, params, body, attempt + 1)
+
+        return self._parse_response(response)
+
+    def _parse_response(self, response: requests.Response) -> Any:
+        content_type = response.headers.get("Content-Type", "")
+        parsed: Any
+        if "application/json" in content_type:
+            try:
+                parsed = response.json()
+            except ValueError:
+                parsed = None
+        else:
+            parsed = response.text or None
+
+        if response.ok:
+            return parsed
+
+        message = _extract_message(parsed) or response.reason or f"HTTP {response.status_code}"
+        status = response.status_code
+
+        if status == 401:
+            raise EvesesAuthError(message, body=parsed)
+        if status == 403:
+            raise EvesesForbiddenError(message, body=parsed)
+        if status == 404:
+            raise EvesesNotFoundError(message, body=parsed)
+        if status in (400, 422):
+            raise EvesesValidationError(message, status, body=parsed)
+        if status == 429:
+            raise EvesesRateLimitError(
+                message,
+                retry_after=_parse_retry_after(response.headers.get("Retry-After")),
+                body=parsed,
+            )
+        if status >= 500:
+            raise EvesesServerError(message, status, body=parsed)
+        raise EvesesError(message, status, body=parsed)
+
+    # --------------------------------------------------------------- helpers --
+    def _build_url(self, path: str) -> str:
+        if not path.startswith("/"):
+            path = "/" + path
+        return f"{self.base_url}{path}"
+
+
+def _clean_params(params: Optional[Mapping[str, Any]]) -> Optional[Dict[str, Any]]:
+    if not params:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _parse_retry_after(value: Optional[str]) -> float:
+    if not value:
+        return 1.0
+    try:
+        seconds = int(value)
+    except (TypeError, ValueError):
+        return 1.0
+    if seconds < 0:
+        return 1.0
+    return float(min(seconds, 60))
+
+
+def _extract_message(body: Any) -> Optional[str]:
+    if isinstance(body, dict):
+        msg = body.get("message")
+        if isinstance(msg, str):
+            return msg
+        err = body.get("error")
+        if isinstance(err, str):
+            return err
+    return None

eveses/exceptions.py

@@ -0,0 +1,76 @@
+"""
+Exception hierarchy for the Eveses SDK.
+
+Every non-2xx response is converted into an EvesesError subclass:
+    400/422 -> EvesesValidationError
+    401     -> EvesesAuthError
+    403     -> EvesesForbiddenError
+    404     -> EvesesNotFoundError
+    429     -> EvesesRateLimitError (after the 1 auto-retry is exhausted)
+    5xx     -> EvesesServerError
+    other   -> EvesesError
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class EvesesError(Exception):
+    """Base class for all SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int = 0,
+        *,
+        code: Optional[str] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.body = body
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        return f"{self.__class__.__name__}({self.status}): {self.message}"
+
+
+class EvesesAuthError(EvesesError):
+    def __init__(self, message: str = "Unauthenticated", body: Any = None) -> None:
+        super().__init__(message, 401, code="unauthenticated", body=body)
+
+
+class EvesesForbiddenError(EvesesError):
+    def __init__(self, message: str = "Forbidden", body: Any = None) -> None:
+        super().__init__(message, 403, code="forbidden", body=body)
+
+
+class EvesesNotFoundError(EvesesError):
+    def __init__(self, message: str = "Not found", body: Any = None) -> None:
+        super().__init__(message, 404, code="not_found", body=body)
+
+
+class EvesesValidationError(EvesesError):
+    def __init__(self, message: str, status: int, body: Any = None) -> None:
+        super().__init__(message or "Validation failed", status, code="validation_failed", body=body)
+        self.errors: Optional[Dict[str, List[str]]] = None
+        if isinstance(body, dict) and isinstance(body.get("errors"), dict):
+            self.errors = body["errors"]
+
+
+class EvesesRateLimitError(EvesesError):
+    def __init__(
+        self,
+        message: str = "Rate limited",
+        retry_after: Optional[float] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message, 429, code="rate_limited", body=body)
+        self.retry_after = retry_after
+
+
+class EvesesServerError(EvesesError):
+    def __init__(self, message: str, status: int, body: Any = None) -> None:
+        super().__init__(message or "Server error", status, code="server_error", body=body)

eveses/wallet.py

@@ -0,0 +1,47 @@
+"""
+Wallet namespace. Hits `/api/account/wallet`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Dict
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .client import Eveses
+
+
+@dataclass
+class WalletBalance:
+    balance: int
+    held_balance: int
+    available_balance: int
+    currency: str
+
+
+class Wallet:
+    def __init__(self, client: "Eveses") -> None:
+        self._client = client
+
+    def balance(self) -> WalletBalance:
+        """Snapshot of total / held / available balance."""
+        res = self._client.request("GET", "/api/account/wallet")
+        d = _unwrap(res)
+        return WalletBalance(
+            balance=_int(d.get("balance"), 0),
+            held_balance=_int(d.get("held_balance"), 0),
+            available_balance=_int(d.get("available_balance"), 0),
+            currency=str(d.get("currency") or "USD"),
+        )
+
+
+def _unwrap(payload: Any) -> Dict[str, Any]:
+    if isinstance(payload, dict) and isinstance(payload.get("data"), dict):
+        return payload["data"]
+    if isinstance(payload, dict):
+        return payload
+    return {}
+
+
+def _int(value: Any, default: int) -> int:
+    return value if isinstance(value, int) else default

eveses/webhooks.py

@@ -0,0 +1,101 @@
+"""
+Webhook signature verification.
+
+Eveses signs every webhook delivery with HMAC-SHA256 over `f"{timestamp}.{body}"`,
+using the endpoint's signing secret. Two headers carry the proof:
+
+    X-Eveses-Signature  -> "sha256=<hex>"
+    X-Eveses-Timestamp  -> unix seconds
+
+Use `Webhooks.verify(...)`. Always pass the **raw** request body (bytes or str),
+not the parsed JSON — round-tripping through json.loads/json.dumps reorders
+keys and breaks the signature.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Optional, Union
+
+
+class Webhooks:
+    """Static-like helpers for webhook verification."""
+
+    @staticmethod
+    def verify(
+        raw_body: Union[str, bytes],
+        signature_header: Optional[str],
+        secret: str,
+        *,
+        timestamp: Optional[Union[str, int, float]] = None,
+        tolerance_seconds: int = 300,
+    ) -> bool:
+        """
+        Verify an Eveses webhook signature.
+
+        :param raw_body:         The raw request body (str or bytes).
+        :param signature_header: Value of `X-Eveses-Signature`, e.g. "sha256=abc123".
+        :param secret:           The endpoint signing secret.
+        :param timestamp:        Value of `X-Eveses-Timestamp` (unix seconds).
+        :param tolerance_seconds: Reject timestamps drifting more than this from now.
+                                  Pass 0 to disable the staleness check.
+        :returns:                True iff the signature is valid and within tolerance.
+        """
+        if not signature_header or not secret:
+            return False
+
+        expected_hex = _strip_prefix(signature_header)
+        if not expected_hex or not all(c in "0123456789abcdefABCDEF" for c in expected_hex):
+            return False
+
+        if timestamp is None or timestamp == "":
+            return False
+        try:
+            ts = int(timestamp)
+        except (TypeError, ValueError):
+            try:
+                ts = int(float(timestamp))
+            except (TypeError, ValueError):
+                return False
+        if ts <= 0:
+            return False
+
+        if tolerance_seconds > 0:
+            now = int(time.time())
+            if abs(now - ts) > tolerance_seconds:
+                return False
+
+        body_bytes = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+        signing_input = f"{ts}.".encode("utf-8") + body_bytes
+        computed = hmac.new(
+            secret.encode("utf-8"),
+            signing_input,
+            hashlib.sha256,
+        ).hexdigest()
+        return hmac.compare_digest(computed, expected_hex.lower())
+
+
+def _strip_prefix(value: str) -> str:
+    trimmed = value.strip()
+    return trimmed[len("sha256=") :] if trimmed.startswith("sha256=") else trimmed
+
+
+# Module-level convenience alias matching the spec's `verify_webhook(...)`.
+def verify_webhook(
+    raw_body: Union[str, bytes],
+    signature_header: Optional[str],
+    secret: str,
+    *,
+    timestamp: Optional[Union[str, int, float]] = None,
+    tolerance_seconds: int = 300,
+) -> bool:
+    """Functional alias for :py:meth:`Webhooks.verify`."""
+    return Webhooks.verify(
+        raw_body,
+        signature_header,
+        secret,
+        timestamp=timestamp,
+        tolerance_seconds=tolerance_seconds,
+    )

eveses-0.1.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: eveses
+Version: 0.1.0
+Summary: Official Eveses SDK — activations, wallet, webhooks.
+Project-URL: Homepage, https://eveses.com
+Project-URL: Source, https://github.com/evesescom/python-sdk
+Author: Eveses
+License: MIT
+Keywords: activations,api,eveses,sdk,sms
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# eveses (Python SDK)
+
+Official Python SDK for the [Eveses](https://eveses.com) developer API.
+Activations, wallet, catalog (countries / services / pricing), and webhook signature verification.
+
+## Install
+
+```bash
+pip install eveses
+```
+
+Requires Python 3.9+ and `requests`.
+
+## Quickstart
+
+```python
+import os
+from eveses import Eveses
+
+client = Eveses(api_key=os.environ["EVESES_API_KEY"])
+
+order = client.activations.create(
+    country="ua",
+    service="telegram",
+    idempotency_key="my-uuid",
+)
+print(order.order_id, order.phone)
+
+wallet = client.wallet.balance()
+print(f"{wallet.available_balance / 100} {wallet.currency}")
+```
+
+## Authentication
+
+Every request sends `Authorization: Bearer <api_key>`. Generate an API key from
+your dashboard (`Settings → API keys`). The token is a Sanctum personal-access
+token with `kind=api_key`.
+
+## Activations
+
+```python
+order = client.activations.create(
+    country="ua",
+    service="telegram",
+    mode="activation",            # or "rent"
+    duration_minutes=60,          # rent only
+    max_price_cents=100,          # optional ceiling
+    idempotency_key="my-uuid",    # also sent as Idempotency-Key header
+)
+
+fresh = client.activations.get(order.order_id)
+sms   = client.activations.sms(order.order_id)
+#   sms.stored — delivered to us via upstream webhook
+#   sms.fresh  — pulled from upstream provider on demand
+
+client.activations.cancel(order.order_id)   # refund-where-supported
+client.activations.finish(order.order_id)   # mark consumed
+```
+
+## Catalog (countries / services / pricing)
+
+Read-only metadata for driving order-creation UX. All three calls hit the
+API-key-authenticated `/api/v1/numbers/*` routes, so the same Bearer token
+that creates orders can populate selectors and price tables.
+
+```python
+countries = client.catalog.countries(mode="activation").countries
+services  = client.catalog.services(mode="activation", country="ua").services
+pricing   = client.catalog.pricing(mode="activation", country="ua", service="telegram")
+#   pricing.services[0].durations[0].price_cents → 50
+```
+
+`mode` accepts ``"activation"`` or ``"rent"``. For rentals, pass
+``duration_minutes=...`` to ``pricing(...)`` to filter to a single duration.
+
+## Webhook verification
+
+Eveses signs every outbound webhook delivery with HMAC-SHA256 over
+`f"{timestamp}.{raw_body}"`. Two headers carry the proof:
+
+- `X-Eveses-Signature` — e.g. `sha256=abc123…`
+- `X-Eveses-Timestamp` — unix seconds
+
+Pass the **raw** request body (bytes or str) — not the parsed JSON. Re-serialising
+through `json.loads` / `json.dumps` reorders keys and breaks the signature.
+
+```python
+# Flask example
+from flask import Flask, request
+from eveses import Webhooks
+
+app = Flask(__name__)
+SECRET = os.environ["EVESES_WEBHOOK_SECRET"]
+
+@app.post("/eveses-webhook")
+def eveses_webhook():
+    raw = request.get_data()  # bytes
+    if not Webhooks.verify(
+        raw,
+        request.headers.get("X-Eveses-Signature"),
+        SECRET,
+        timestamp=request.headers.get("X-Eveses-Timestamp"),
+    ):
+        return "bad signature", 401
+
+    payload = request.get_json()
+    # handle payload["event"] / payload["data"] …
+    return "", 204
+```
+
+A functional alias is also exported:
+
+```python
+from eveses import verify_webhook
+ok = verify_webhook(raw, sig_header, SECRET, timestamp=ts_header)
+```
+
+## Errors
+
+All non-2xx responses raise a typed subclass of `EvesesError`:
+
+| Status | Class |
+| --- | --- |
+| 400 / 422 | `EvesesValidationError` (with `.errors`) |
+| 401 | `EvesesAuthError` |
+| 403 | `EvesesForbiddenError` |
+| 404 | `EvesesNotFoundError` |
+| 429 | `EvesesRateLimitError` (only after the 1 auto-retry is exhausted) |
+| 5xx | `EvesesServerError` |
+| other | `EvesesError` |
+
+```python
+from eveses import EvesesValidationError
+
+try:
+    client.activations.create(country="", service="")
+except EvesesValidationError as e:
+    print(e.errors)
+```
+
+## API surface vs OpenAPI
+
+The Eveses public OpenAPI spec exposes the customer-facing endpoints under
+`/api/account/*` (legacy account scope) and `/api/v1/numbers/*` (new versioned
+public API). For API-key consumers (`kind=api_key` Sanctum tokens), the v1
+surface is currently a **thin wrapper** around the same controllers — orders
+and wallet are still served from `/api/account/*`. This SDK targets the
+account-scoped routes, which is where v1 reads & writes terminate today. When
+v1 ships its own activations / wallet routes, you can override the base URL
+without changing call sites; the response shapes are identical.
+
+## Configuration
+
+```python
+client = Eveses(
+    api_key="…",
+    base_url="https://api.eveses.com",  # override per environment
+    timeout=30.0,
+    session=requests.Session(),         # inject for tests / connection pooling
+    default_headers={"X-Trace-Id": "t1"},
+    user_agent="my-app/1.2.3",
+)
+```
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+python -m unittest discover -s tests
+```
+
+## License
+
+MIT

eveses-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+eveses/__init__.py,sha256=-gp39rS_lH636BO9JEaJ7fR7zC3DkaCi5eE-qYKOAdQ,1573
+eveses/activations.py,sha256=7konMn5UnpoJdgDTco45HxEa-bdPvcR55ciAi_qxthg,4966
+eveses/catalog.py,sha256=2CXnmr_Mz7oC3UqqR31mDvJ_AXH8Jvih5sRQlxnudcY,6988
+eveses/client.py,sha256=mJ1guHZHhcFnynE03XcnQ0L2R0KihS4RsX3D0oXQAGQ,6295
+eveses/exceptions.py,sha256=pnRrlphw9EC5wH-ogttQpdXYIuJbD782Bmwj7pmnoPQ,2483
+eveses/wallet.py,sha256=gRzcBBh7nmHaW6TcVkwHAp-joFMDZaGFBKrb6e0uzaI,1235
+eveses/webhooks.py,sha256=peX0H-FJ8QIsfBCpvibiwa7I2dpBuVGsMBFIyfVMmA4,3284
+eveses-0.1.0.dist-info/METADATA,sha256=L6c1e2v2FTYbRH29JCwbCo-By_vW8MTuagYqZTr1cn4,5957
+eveses-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+eveses-0.1.0.dist-info/RECORD,,

eveses-0.1.0.dist-info/WHEEL

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