eveses 0.1.0__tar.gz

eveses-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,174 @@
+# 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/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-0.1.0/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="")