fazercards-python-sdk 0.1.1__py3-none-any.whl

fazercards_sdk/config.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+from urllib.parse import quote, urlencode, urlsplit
+
+from goodconf import Field, GoodConf, GoodConfConfigDict
+from pydantic import BaseModel, SecretStr, field_validator
+
+from ._version import __version__
+from .errors import ConfigurationError
+from .messages import text
+
+LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+class Endpoints(BaseModel):
+    me: str = "/me"
+    balance: str = "/balance"
+    webhook: str = "/account/webhook"
+    topup_categories: str = "/topups"
+    topup_offers: str = "/topups/offers"
+    topup_order: str = "/topups/order"
+    validate_id: str = "/topups/validate-id"
+    giftcard_categories: str = "/giftcards"
+    giftcard_offers: str = "/giftcards/cards"
+    giftcard_order: str = "/giftcards/order"
+    orders: str = "/orders"
+    order: str = "/orders/{order_id}"
+    stars_quote: str = "/telegram/stars"
+    stars_buy: str = "/telegram/stars/buy"
+    premium_quote: str = "/telegram/premium"
+    premium_buy: str = "/telegram/premium/buy"
+    steam_rates: str = "/steam-topup/rates"
+    steam_login: str = "/steam-topup/check-login"
+    steam_order: str = "/steam-topup/order"
+
+
+class Settings(GoodConf):
+    model_config = GoodConfConfigDict(
+        env_prefix="FAZERCARDS_",
+        file_env_var="FAZERCARDS_CONFIG",
+        default_files=["fazercards.toml", "fazercards.yaml", "fazercards.yml", "fazercards.json"],
+        extra="ignore",
+        env_nested_delimiter="__",
+    )
+
+    api_key: SecretStr = Field(default=SecretStr(""), description=text("settings.api_key"))
+    base_url: str = Field(default="https://api.fzr.cards/api/v2", description=text("settings.base_url"))
+    endpoints: Endpoints = Field(default_factory=Endpoints, description=text("settings.endpoints"))
+    webhook_secret: SecretStr = Field(default=SecretStr(""), description=text("settings.webhook_secret"))
+    idempotency_prefix: str = Field(default="", description=text("settings.idempotency_prefix"))
+    timeout: float = Field(default=30.0, gt=0, description=text("settings.timeout"))
+    connect_timeout: float = Field(default=10.0, gt=0, description=text("settings.connect_timeout"))
+    max_retries: int = Field(default=2, ge=0, le=10, description=text("settings.max_retries"))
+    backoff_base: float = Field(default=0.5, ge=0, description=text("settings.backoff_base"))
+    backoff_cap: float = Field(default=8.0, ge=0, description=text("settings.backoff_cap"))
+    resend_keyed_orders: bool = Field(default=False, description=text("settings.resend_keyed_orders"))
+    code_checks: int = Field(default=3, ge=0, le=20, description=text("settings.code_checks"))
+    code_check_wait: float = Field(default=1.0, ge=0, description=text("settings.code_check_wait"))
+    user_agent: str = Field(default="fazercards-python-sdk/{version}", description=text("settings.user_agent"))
+    allow_insecure_http: bool = Field(default=False, description=text("settings.allow_insecure_http"))
+
+    @field_validator("base_url")
+    @classmethod
+    def _base_url(cls, value: str) -> str:
+        parts = urlsplit(value.strip())
+        if parts.scheme not in ("http", "https") or not parts.hostname:
+            raise ValueError(text("error.base_url", url=value))
+        return value.strip().rstrip("/")
+
+    def check_transport(self) -> None:
+        parts = urlsplit(self.base_url)
+        if parts.scheme == "https" or self.allow_insecure_http or parts.hostname in LOCAL_HOSTS:
+            return
+        raise ConfigurationError(text("error.insecure", url=self.base_url))
+
+    def path(self, endpoint: str, **params: Any) -> str:
+        template = endpoint if endpoint.startswith("/") else getattr(self.endpoints, endpoint)
+        return str(template.format(**{k: quote(str(v), safe="") for k, v in params.items()}))
+
+    def url(self, endpoint: str, query: Optional[dict[str, Any]] = None, **params: Any) -> str:
+        address = self.base_url + self.path(endpoint, **params)
+        given = {k: v for k, v in (query or {}).items() if v is not None and v != ""}
+        return f"{address}?{urlencode(given)}" if given else address
+
+    def resolved_user_agent(self) -> str:
+        return self.user_agent.replace("{version}", __version__)
+
+    def key(self) -> str:
+        value = self.api_key.get_secret_value().strip()
+        if not value:
+            raise ConfigurationError(text("error.missing_key"))
+        return value
+
+    def scoped(self, key: str) -> str:
+        return f"{self.idempotency_prefix}:{key}" if self.idempotency_prefix else key
+
+
+Settings.__doc__ = text("settings.description")
+
+
+def load_settings(config_file: Optional[str] = None, **overrides: Any) -> Settings:
+    given = {key: value for key, value in overrides.items() if value is not None}
+    return Settings(load=True, config_file=config_file, **given)

fazercards_sdk/enums.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+
+class _Text(str, Enum):
+    def __str__(self) -> str:
+        return str(self.value)
+
+
+class OrderStatus(_Text):
+    CREATED = "created"
+    PENDING = "pending"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    DELIVERED = "delivered"
+    SUCCESS = "success"
+    FAILED = "failed"
+    REFUND = "refund"
+    REFUNDED = "refunded"
+    CANCELLED = "cancelled"
+    CANCELED = "canceled"
+    ERROR = "error"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def of(cls, value: Any) -> OrderStatus:
+        text = str(value or "").strip().lower()
+        try:
+            return cls(text)
+        except ValueError:
+            return cls.UNKNOWN
+
+    @property
+    def delivered(self) -> bool:
+        return self in _DELIVERED
+
+    @property
+    def failed(self) -> bool:
+        return self in _FAILED
+
+    @property
+    def in_flight(self) -> bool:
+        return self in _IN_FLIGHT
+
+    @property
+    def final(self) -> bool:
+        return self.delivered or self.failed
+
+
+_DELIVERED = frozenset({OrderStatus.COMPLETED, OrderStatus.DELIVERED, OrderStatus.SUCCESS})
+_FAILED = frozenset(
+    {
+        OrderStatus.FAILED,
+        OrderStatus.REFUND,
+        OrderStatus.REFUNDED,
+        OrderStatus.CANCELLED,
+        OrderStatus.CANCELED,
+        OrderStatus.ERROR,
+    }
+)
+_IN_FLIGHT = frozenset({OrderStatus.CREATED, OrderStatus.PENDING, OrderStatus.PROCESSING})
+
+
+class OrderKind(_Text):
+    TOPUP = "topup"
+    GIFT_CARD = "gift_card"
+    TELEGRAM_STARS = "telegram_stars"
+    TELEGRAM_PREMIUM = "telegram_premium"
+    STEAM_TOPUP = "steam_topup"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def of(cls, value: Any) -> OrderKind:
+        text = str(value or "").strip().lower()
+        try:
+            return cls(text)
+        except ValueError:
+            return cls.UNKNOWN
+
+
+class SteamCurrency(_Text):
+    USD = "USD"
+    RUB = "RUB"
+    UAH = "UAH"
+    KZT = "KZT"
+
+
+PREMIUM_MONTHS = (3, 6, 12)

fazercards_sdk/errors.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class FazerCardsError(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class ConfigurationError(FazerCardsError):
+    pass
+
+
+class InvalidRequestError(FazerCardsError, ValueError):
+    pass
+
+
+class SignatureError(FazerCardsError):
+    pass
+
+
+class TransportError(FazerCardsError):
+    def __init__(self, message: str, *, path: str = "", idempotency_key: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.path = path
+        self.idempotency_key = idempotency_key
+
+
+class NotSentError(TransportError):
+    pass
+
+
+class OutcomeUnknownError(TransportError):
+    def __init__(self, message: str, *, status_code: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.status_code = status_code
+
+
+class APIError(FazerCardsError):
+    def __init__(self, message: str, *, status_code: int, body: Any = None, path: str = "") -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.path = path
+
+    def __str__(self) -> str:
+        return f"[{self.status_code}] {self.message}"
+
+
+class BadRequestError(APIError):
+    pass
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class ConflictError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    def __init__(self, message: str, *, retry_after: Optional[float] = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(APIError):
+    pass
+
+
+class KeyCollisionError(FazerCardsError):
+    def __init__(self, message: str, *, idempotency_key: str, order: Any = None) -> None:
+        super().__init__(message)
+        self.idempotency_key = idempotency_key
+        self.order = order
+
+
+class WaitTimeoutError(FazerCardsError):
+    def __init__(self, message: str, *, order: Any = None) -> None:
+        super().__init__(message)
+        self.order = order
+
+
+def for_status(status: int) -> type[APIError]:
+    if status in (401, 403):
+        return AuthenticationError
+    if status == 404:
+        return NotFoundError
+    if status == 409:
+        return ConflictError
+    if status == 429:
+        return RateLimitError
+    if status >= 500:
+        return ServerError
+    if status >= 400:
+        return BadRequestError
+    return APIError

fazercards_sdk/messages.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib import resources
+from pathlib import Path
+from typing import Any, Union
+
+import yaml
+
+PathLike = Union[str, Path]
+
+_PACKAGE_FILE = "messages.yaml"
+_catalog: dict[str, str] = {}
+
+
+def _flatten(node: Mapping[str, Any], prefix: str = "") -> dict[str, str]:
+    flat: dict[str, str] = {}
+    for key, value in node.items():
+        path = f"{prefix}{key}"
+        if isinstance(value, Mapping):
+            flat.update(_flatten(value, f"{path}."))
+        else:
+            flat[path] = str(value)
+    return flat
+
+
+def _parse(raw: str) -> dict[str, str]:
+    data = yaml.safe_load(raw) or {}
+    if not isinstance(data, Mapping):
+        raise ValueError("messages file must contain a mapping")
+    return _flatten(data)
+
+
+def _read_packaged() -> dict[str, str]:
+    raw = resources.files(__package__).joinpath(_PACKAGE_FILE).read_text(encoding="utf-8")
+    return _parse(raw)
+
+
+def catalog() -> Mapping[str, str]:
+    if not _catalog:
+        _catalog.update(_read_packaged())
+    return _catalog
+
+
+def use(source: PathLike | Mapping[str, Any]) -> None:
+    overrides = _flatten(source) if isinstance(source, Mapping) else _parse(Path(source).read_text(encoding="utf-8"))
+    unknown = set(overrides) - set(_read_packaged())
+    if unknown:
+        raise KeyError(", ".join(sorted(unknown)))
+    catalog()
+    _catalog.update(overrides)
+
+
+def reset() -> None:
+    _catalog.clear()
+
+
+def text(key: str, **params: Any) -> str:
+    template = catalog()[key]
+    return template.format(**params) if params else template

fazercards_sdk/messages.yaml

@@ -0,0 +1,48 @@
+settings:
+  description: Settings for the FazerCards client. Values come from code, FAZERCARDS_* environment variables or a config file.
+  api_key: Reseller API key, sent as X-API-Key
+  base_url: API address, including the version path
+  endpoints: Path of every API call, relative to base_url
+  webhook_secret: Secret used to check the X-Webhook-Signature header of webhooks
+  idempotency_prefix: Text put in front of every Idempotency-Key, to keep two shops on one account apart
+  timeout: Seconds to wait for an answer
+  connect_timeout: Seconds to wait for a connection
+  max_retries: Extra attempts for calls that are safe to repeat
+  backoff_base: First wait between retries, in seconds
+  backoff_cap: Longest wait between retries, in seconds
+  resend_keyed_orders: Resend an order once with the same Idempotency-Key after a timeout or a 5xx
+  code_checks: Extra reads of a gift card order that came back completed without codes
+  code_check_wait: Seconds between those reads
+  user_agent: User-Agent header
+  allow_insecure_http: Allow a plain http base_url outside localhost, for a test server on a private network only
+
+value:
+  empty: "{field} cannot be empty"
+  too_long: "{field} is longer than {limit} characters"
+  range: "{field} must be a whole number from {low} to {high}, got {value!r}"
+  choice: "{field} must be one of {choices}, got {value!r}"
+  amount_type: "{field} must be a number, got {value!r}"
+  amount_positive: "{field} must be greater than zero, got {value}"
+  amount_scale: "{field} {value} has more than two decimal places"
+  amount_finite: "{field} must be a finite number, got {value}"
+  order_id: "order_id must be a FazerCards order id such as ord-123, got {value!r}"
+  fields: "fields must map names to text, got {value!r}"
+  username: "username must be a Telegram username of 4 to 32 letters, digits or _, got {value!r}"
+  url: "url must be an absolute https address, got {value!r}"
+
+error:
+  missing_key: FazerCards api_key is required
+  missing_secret: FazerCards webhook_secret is required to check webhooks
+  base_url: "base_url must be an absolute http or https address, got {url}"
+  insecure: "Refusing to send the API key over plain http to {url}. Use https, or set allow_insecure_http for a private test server."
+  connect: "Could not reach FazerCards, nothing was sent: {error}"
+  timeout: "FazerCards did not answer: {error}"
+  unknown_outcome: "The order may or may not have been placed ({reason}). Look it up before trying again."
+  body: "FazerCards sent an answer that is not JSON: {body}"
+  status: "FazerCards answered with HTTP {status}"
+  refused: FazerCards refused the request
+  collision: "Idempotency-Key {idempotency_key} already belongs to order {order_id} for a different item"
+  signature: Webhook signature does not match
+  payload_size: "Webhook body is larger than {limit} bytes"
+  payload: Webhook body is not a JSON object
+  wait_timeout: "Order {order_id} is still {status} after {seconds} seconds"