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

fazercards_python_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: fazercards-python-sdk
+Version: 0.1.1
+Summary: Typed Python client for the FazerCards reseller API: game top-ups, gift cards, Telegram Stars and Premium, Steam wallet. Sync and async.
+Project-URL: Homepage, https://theqiyas.cc/projects/fazercards-sdk/
+Project-URL: Source, https://github.com/qiyascc/fazercards-python-sdk
+Project-URL: Author, https://theqiyas.cc
+Project-URL: Issues, https://github.com/qiyascc/fazercards-python-sdk/issues
+Project-URL: Changelog, https://github.com/qiyascc/fazercards-python-sdk/blob/main/CHANGELOG.md
+Author-email: qiyascc <qiyasturk@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,fazercards,gift cards,reseller,sdk,steam,telegram stars,top-up
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: goodconf>=7.1
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: goodconf[toml]>=7.1; extra == 'dev'
+Requires-Dist: goodconf[yaml]>=7.1; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: toml
+Requires-Dist: goodconf[toml]>=7.1; extra == 'toml'
+Provides-Extra: yaml
+Requires-Dist: goodconf[yaml]>=7.1; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# fazercards-python-sdk
+
+[![Python](https://img.shields.io/badge/python-3.10%20to%203.13-3776AB?logo=python&logoColor=white)](https://www.python.org)
+[![FazerCards](https://img.shields.io/badge/api-FazerCards%20v2-7C3AED)](https://api.fzr.cards/api/v2)
+[![Typed](https://img.shields.io/badge/typing-mypy-2A6DB2)](https://mypy-lang.org)
+[![Async](https://img.shields.io/badge/sync%20%2B%20async-httpx-5A45FF)](https://www.python-httpx.org)
+[![Ruff](https://img.shields.io/badge/lint-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/qiyascc/fazercards-python-sdk/blob/main/LICENSE)
+
+Typed Python client for the FazerCards reseller API. Game top-ups, gift cards, Telegram Stars and Premium, Steam wallet, orders and signed webhooks. Sync and async, with retry rules built so an order is never placed twice.
+
+```bash
+pip install fazercards-python-sdk
+```
+
+## Top up a game
+
+```python
+from fazercards_sdk import FazerCards
+
+with FazerCards("API_KEY") as fc:
+    check = fc.topups.validate("free_fire", "123456789")
+    if check.valid:
+        order = fc.topups.order("free_fire_cis", "110_diamonds", "123456789", idempotency_key="ORDER-1042")
+```
+
+`order.status` moves from `created` to `processing` to `completed`, or to `failed` / `refund` with `order.fail_reason`. Follow it by webhook, or with `fc.orders.wait(order.id)`.
+
+## Sell a gift card
+
+```python
+order = fc.giftcards.order("playstation_tr", "250_try", quantity=1, idempotency_key="ORDER-1043")
+order.codes
+```
+
+FazerCards can answer a gift card order with `completed` and an empty `cards` list, then fill the list a moment later. The client reads the order again before it returns (`code_checks`, default 3). If the codes still have not arrived, `order.awaiting_codes` is `True`: keep the order open and read it later, never show the customer an empty result.
+
+## Telegram and Steam
+
+```python
+fc.telegram.stars_quote().price(500)
+fc.telegram.buy_stars("@username", 500)
+fc.telegram.buy_premium("username", months=12)
+
+if fc.steam.check_login("steam_login").valid:
+    fc.steam.order("steam_login", "19.50", "USD", idempotency_key="ORDER-1044")
+```
+
+## Catalog
+
+```python
+games = fc.topups.all_categories()
+cards = fc.giftcards.all_categories()
+offers = fc.topups.offers("free_fire_cis")
+offers.get("110_diamonds").price
+offers.fields
+fc.giftcards.cards("playstation_tr").offers[0].stock
+```
+
+Categories come in cursor pages of up to 500 (`fc.topups.categories(limit, cursor)`); `all_categories()` follows the cursor. Orders come in numbered pages of up to 100 (`fc.orders.list(page, limit)`, `fc.orders.recent(count)`).
+
+## Webhooks
+
+```python
+event = fc.verify_webhook(request.body, headers=request.headers)
+if event.needs_lookup:
+    order = fc.orders.get(event.order_id)
+```
+
+The body is checked against `X-Webhook-Signature` (HMAC SHA256 of the raw body, `sha256=` prefix optional) in constant time. Set the address with `fc.account.set_webhook("https://shop.example/webhook/fazercards")`. See [examples/fastapi_webhook.py](https://github.com/qiyascc/fazercards-python-sdk/blob/main/examples/fastapi_webhook.py).
+
+## Safety
+
+| Situation | What the client does |
+| --- | --- |
+| Connection refused, nothing sent | Retries, then `NotSentError` |
+| Timeout, cut connection or 5xx on an order | No retry, `OutcomeUnknownError` with the `idempotency_key` |
+| Same failure on a read | Retries with backoff, then `TransportError` |
+| 429 | Waits `Retry-After` and retries, the request was not processed |
+| `resend_keyed_orders=True` | An order with an Idempotency-Key is resent once with the same key |
+| Telegram purchase | Takes no key on the API side, so it is never resent |
+| Reused key that returns another item | `KeyCollisionError`, never counted as success |
+| Gift card `completed` without codes | Read again, then `order.awaiting_codes` |
+| Quantity, months, amount like `1.005` or `True` | `InvalidRequestError` before anything is sent |
+| `base_url` over plain http | `ConfigurationError`, except localhost or `allow_insecure_http` |
+| Webhook body over 256 KB | Rejected before hashing |
+
+Every top-up, gift card and Steam order carries an `Idempotency-Key`. Pass your own order number, so a double click or a crash can not buy twice. With several shops on one account set `idempotency_prefix`. Prices are `Decimal` end to end. `fc.rate_limit` keeps the last `X-RateLimit-*` headers.
+
+## Endpoints
+
+| Namespace | Methods |
+| --- | --- |
+| `topups` | `categories` `all_categories` `offers` `validation_games` `validate` `order` |
+| `giftcards` | `categories` `all_categories` `cards` `order` |
+| `orders` | `get` `list` `recent` `wait` |
+| `telegram` | `stars_quote` `premium_quote` `buy_stars` `buy_premium` |
+| `steam` | `rates` `check_login` `order` |
+| `account` | `me` `balance` `webhook` `set_webhook` |
+| client | `balance` `verify_webhook` `request` |
+
+`AsyncFazerCards` has the same methods, awaited.
+
+## Errors
+
+`FazerCardsError` is the base. API answers raise `APIError` subclasses by status: `BadRequestError` (400), `AuthenticationError` (401, 403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429), `ServerError` (5xx). Each carries `status_code`, `message` and the raw `body`.
+
+## Config
+
+Pass values in code, or set `FAZERCARDS_API_KEY`, `FAZERCARDS_WEBHOOK_SECRET`, `FAZERCARDS_BASE_URL`, `FAZERCARDS_IDEMPOTENCY_PREFIX`, `FAZERCARDS_TIMEOUT`, `FAZERCARDS_MAX_RETRIES`, or put them in `fazercards.toml` ([example](https://github.com/qiyascc/fazercards-python-sdk/blob/main/examples/fazercards.toml)). Every path is a setting (`FAZERCARDS_ENDPOINTS__BALANCE=...`). Messages live in `messages.yaml` and can be replaced with `messages.use(...)`.
+
+## Develop
+
+```bash
+pip install -e ".[dev]" && pytest && ruff check . && mypy src
+```
+
+## Links
+
+- Source code: [github.com/qiyascc/fazercards-python-sdk](https://github.com/qiyascc/fazercards-python-sdk)
+- PyPI: [pypi.org/project/fazercards-python-sdk](https://pypi.org/project/fazercards-python-sdk/)
+- Project page: [theqiyas.cc/projects/fazercards-sdk](https://theqiyas.cc/projects/fazercards-sdk/)
+- Author: [Qiyas Sadıqov](https://theqiyas.cc), more projects at [theqiyas.cc](https://theqiyas.cc)
+
+## License
+
+MIT

fazercards_python_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+fazercards_sdk/__init__.py,sha256=AysBsfdOd4jDhLYXs1tQjdyPARFrui8PZKgFsDHVOi0,2052
+fazercards_sdk/_core.py,sha256=Y0tnk8n-5tCOcRjgSXkSaj2m8C6qe2lMqmY27fWrMTE,11875
+fazercards_sdk/_version.py,sha256=rnObPjuBcEStqSO0S6gsdS_ot8ITOQjVj_-P1LUUYpg,22
+fazercards_sdk/client.py,sha256=GyEvSad-98dJfQp3VLLSDd7DOp4vO5cCZhoBIfhX6t8,2357
+fazercards_sdk/config.py,sha256=MiwX819rKAyCasBuK0EDpqgzdnDdYlWOFtvXqi2Wko0,4836
+fazercards_sdk/enums.py,sha256=dvkzzKWyCMmHTQcfJruUjj9wU0jzJnq_IlO5EHNukfE,1997
+fazercards_sdk/errors.py,sha256=NDW807_MKJxpOC6R-9uYrlKxNENJztZJ8QwhWJH73Ms,2493
+fazercards_sdk/messages.py,sha256=GqqTi5PvVlt2G-F6llTb3_gMTlRgVj4DHMUXZQzr7ZY,1601
+fazercards_sdk/messages.yaml,sha256=5rcfGJE22gQytpqEk15umXvXjGRIC7uOAmEWwSm7i5U,2970
+fazercards_sdk/models.py,sha256=PIt4-ToSq4dazC79LCcgPf4vnUZMoSA0qSmzFfLHmRE,17466
+fazercards_sdk/money.py,sha256=MVwXYsrAvR1Hfyd44ePf-pXyNonaNY9n6smuF9dVFFw,1431
+fazercards_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fazercards_sdk/resources.py,sha256=vgzF_2wNi-W9c3t5V9p95aggapvZV9wSeqLVCYyW7Lw,12361
+fazercards_sdk/webhooks.py,sha256=xuGA4sepDpbvOwvon4Ofi60TIsTgCyPJxLymD8zsN6U,2003
+fazercards_python_sdk-0.1.1.dist-info/METADATA,sha256=naMxzWFEwEaios1wfbECAziEd19dMNbijpGv5VYjiek,8130
+fazercards_python_sdk-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+fazercards_python_sdk-0.1.1.dist-info/licenses/LICENSE,sha256=ENVL-_Eh4n1SumZuLuTjO2K0OOL_eXh4pkeme35b02I,1064
+fazercards_python_sdk-0.1.1.dist-info/RECORD,,

fazercards_python_sdk-0.1.1.dist-info/WHEEL

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

fazercards_python_sdk-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qiyascc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fazercards_sdk/__init__.py

@@ -0,0 +1,102 @@
+from . import messages, webhooks
+from ._version import __version__
+from .client import AsyncFazerCards, FazerCards
+from .config import Endpoints, Settings, load_settings
+from .enums import PREMIUM_MONTHS, OrderKind, OrderStatus, SteamCurrency
+from .errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConfigurationError,
+    ConflictError,
+    FazerCardsError,
+    InvalidRequestError,
+    KeyCollisionError,
+    NotFoundError,
+    NotSentError,
+    OutcomeUnknownError,
+    RateLimitError,
+    ServerError,
+    SignatureError,
+    TransportError,
+    WaitTimeoutError,
+)
+from .models import (
+    Account,
+    Balance,
+    Category,
+    CategoryPage,
+    InputField,
+    Offer,
+    Offers,
+    Order,
+    OrderPage,
+    PlayerCheck,
+    PremiumPlan,
+    PremiumQuote,
+    RateLimit,
+    StarsQuote,
+    StatusChange,
+    SteamLogin,
+    SteamRates,
+    ValidationGame,
+    Webhook,
+    WebhookEvent,
+    card_code,
+)
+from .webhooks import SIGNATURE_HEADER, parse_webhook, verify_webhook
+
+__all__ = [
+    "__version__",
+    "FazerCards",
+    "AsyncFazerCards",
+    "Settings",
+    "Endpoints",
+    "load_settings",
+    "messages",
+    "webhooks",
+    "verify_webhook",
+    "parse_webhook",
+    "SIGNATURE_HEADER",
+    "OrderStatus",
+    "OrderKind",
+    "SteamCurrency",
+    "PREMIUM_MONTHS",
+    "Account",
+    "Balance",
+    "Category",
+    "CategoryPage",
+    "InputField",
+    "Offer",
+    "Offers",
+    "Order",
+    "OrderPage",
+    "PlayerCheck",
+    "PremiumPlan",
+    "PremiumQuote",
+    "RateLimit",
+    "StarsQuote",
+    "StatusChange",
+    "SteamLogin",
+    "SteamRates",
+    "ValidationGame",
+    "Webhook",
+    "WebhookEvent",
+    "card_code",
+    "FazerCardsError",
+    "ConfigurationError",
+    "InvalidRequestError",
+    "SignatureError",
+    "TransportError",
+    "NotSentError",
+    "OutcomeUnknownError",
+    "APIError",
+    "BadRequestError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "KeyCollisionError",
+    "WaitTimeoutError",
+]

fazercards_sdk/_core.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Generator, Mapping, Optional, TypeVar
+
+import httpx
+
+from .config import Settings, load_settings
+from .errors import (
+    APIError,
+    KeyCollisionError,
+    NotSentError,
+    OutcomeUnknownError,
+    RateLimitError,
+    TransportError,
+    for_status,
+)
+from .messages import text
+from .models import RateLimit
+
+T = TypeVar("T")
+
+NOT_SENT = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout, httpx.UnsupportedProtocol)
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+@dataclass
+class Op:
+    method: str
+    endpoint: str
+    parse: Callable[[Any], Any] = lambda body: body
+    query: Optional[dict[str, Any]] = None
+    body: Optional[dict[str, Any]] = None
+    path_params: Mapping[str, Any] = field(default_factory=dict)
+    safe: bool = False
+    key: Optional[str] = None
+    echo: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Pause:
+    seconds: float
+
+
+Step = Any
+Flow = Generator[Step, Any, T]
+
+
+class Outcome:
+    def __init__(self, value: Any = None, error: Optional[Exception] = None, wait: Optional[float] = None) -> None:
+        self.value = value
+        self.error = error
+        self.wait = wait
+
+
+def _number(value: Optional[str]) -> Optional[float]:
+    try:
+        return float(value) if value not in (None, "") else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _echo_mismatch(body: Any, expected: Mapping[str, Any]) -> Optional[str]:
+    order = body.get("order", body) if isinstance(body, Mapping) else None
+    if not isinstance(order, Mapping):
+        return None
+    given = order.get("fields")
+    fields: Mapping[str, Any] = given if isinstance(given, Mapping) else {}
+    actual = {
+        "category_id": order.get("category_id"),
+        "offer_id": order.get("offer_id") or order.get("card_id"),
+        "player_id": fields.get("player_id"),
+    }
+    for name, value in expected.items():
+        seen = actual.get(name)
+        if value not in (None, "") and seen is not None and str(seen) != str(value):
+            return str(order.get("id") or order.get("order_id") or "?")
+    return None
+
+
+class Engine:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        settings: Optional[Settings] = None,
+        config_file: Optional[str] = None,
+        **overrides: Any,
+    ) -> None:
+        if settings is None:
+            settings = load_settings(config_file, api_key=api_key, **overrides)
+        elif api_key or overrides:
+            current = settings.model_dump()
+            current["api_key"] = settings.api_key.get_secret_value()
+            current["webhook_secret"] = settings.webhook_secret.get_secret_value()
+            changes = {k: v for k, v in dict(overrides, api_key=api_key).items() if v is not None}
+            settings = load_settings(None, **{**current, **changes})
+        self.settings = settings
+        settings.check_transport()
+        self._api_key = settings.key()
+        self.rate_limit: Optional[RateLimit] = None
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(base_url={self.settings.base_url!r})"
+
+    def _timeout(self) -> httpx.Timeout:
+        return httpx.Timeout(self.settings.timeout, connect=self.settings.connect_timeout)
+
+    def _headers(self, op: Op) -> dict[str, str]:
+        headers = {
+            "X-API-Key": self._api_key,
+            "Accept": "application/json",
+            "User-Agent": self.settings.resolved_user_agent(),
+        }
+        if op.key:
+            headers["Idempotency-Key"] = op.key
+        return headers
+
+    def _request_args(self, op: Op) -> dict[str, Any]:
+        args: dict[str, Any] = {"headers": self._headers(op)}
+        if op.method != "GET":
+            args["json"] = op.body or {}
+        return args
+
+    def _backoff(self, attempt: int) -> float:
+        base = self.settings.backoff_base
+        return min(self.settings.backoff_cap, base * (2**attempt)) + random.uniform(0, base / 2)
+
+    def _resend(self, op: Op, attempt: int) -> bool:
+        return bool(op.key) and self.settings.resend_keyed_orders and attempt == 0
+
+    def _remember_limits(self, response: httpx.Response) -> None:
+        headers = response.headers
+        if "x-ratelimit-limit" not in headers:
+            return
+        limit, remaining = _number(headers.get("x-ratelimit-limit")), _number(headers.get("x-ratelimit-remaining"))
+        self.rate_limit = RateLimit(
+            int(limit) if limit is not None else None,
+            int(remaining) if remaining is not None else None,
+            _number(headers.get("x-ratelimit-reset")),
+        )
+
+    def _on_exception(self, op: Op, exc: Exception, attempt: int) -> Outcome:
+        path = self.settings.path(op.endpoint, **op.path_params)
+        can_retry = attempt < self.settings.max_retries
+        if isinstance(exc, NOT_SENT):
+            if can_retry:
+                return Outcome(wait=self._backoff(attempt))
+            return Outcome(error=NotSentError(text("error.connect", error=exc), path=path, idempotency_key=op.key))
+        if op.safe:
+            if can_retry:
+                return Outcome(wait=self._backoff(attempt))
+            return Outcome(error=TransportError(text("error.timeout", error=exc), path=path, idempotency_key=op.key))
+        if self._resend(op, attempt):
+            return Outcome(wait=self._backoff(attempt))
+        return Outcome(error=OutcomeUnknownError(text("error.unknown_outcome", reason=type(exc).__name__), path=path,
+                                                 idempotency_key=op.key))
+
+    def _on_response(self, op: Op, response: httpx.Response, attempt: int) -> Outcome:
+        self._remember_limits(response)
+        path = self.settings.path(op.endpoint, **op.path_params)
+        status = response.status_code
+        can_retry = attempt < self.settings.max_retries
+        if status == 429 and can_retry:
+            hint = _number(response.headers.get("retry-after")) or _number(response.headers.get("x-ratelimit-reset"))
+            return Outcome(wait=min(self.settings.backoff_cap, hint) if hint is not None else self._backoff(attempt))
+        if status in RETRY_STATUSES and status != 429:
+            if op.safe and can_retry:
+                return Outcome(wait=self._backoff(attempt))
+            if not op.safe:
+                if self._resend(op, attempt):
+                    return Outcome(wait=self._backoff(attempt))
+                return Outcome(error=OutcomeUnknownError(text("error.unknown_outcome", reason=f"HTTP {status}"),
+                                                         status_code=status, path=path, idempotency_key=op.key))
+        try:
+            body = response.json()
+        except ValueError:
+            snippet = response.text[:200]
+            if status < 400 and not op.safe:
+                return Outcome(error=OutcomeUnknownError(text("error.body", body=snippet), status_code=status,
+                                                         path=path, idempotency_key=op.key))
+            return Outcome(error=for_status(status)(text("error.body", body=snippet), status_code=status,
+                                                    body=snippet, path=path))
+        refused = isinstance(body, Mapping) and body.get("ok") is False
+        if status >= 400 or refused:
+            message = (body.get("message") or body.get("error")) if isinstance(body, Mapping) else None
+            kind = for_status(status) if status >= 400 else APIError
+            error_args: dict[str, Any] = {"status_code": status, "body": body, "path": path}
+            if kind is RateLimitError:
+                error_args["retry_after"] = _number(response.headers.get("retry-after"))
+            return Outcome(error=kind(str(message or text("error.refused")), **error_args))
+        if op.key and op.echo:
+            other = _echo_mismatch(body, op.echo)
+            if other is not None:
+                return Outcome(error=KeyCollisionError(text("error.collision", idempotency_key=op.key, order_id=other),
+                                                       idempotency_key=op.key, order=body))
+        return Outcome(value=op.parse(body))
+
+
+class SyncEngine(Engine):
+    def __init__(self, *args: Any, http_client: Optional[httpx.Client] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(timeout=self._timeout())
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self: T) -> T:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def _sleep(self, seconds: float) -> None:
+        if seconds > 0:
+            time.sleep(seconds)
+
+    def _run(self, op: Op) -> Any:
+        url = self.settings.url(op.endpoint, op.query, **op.path_params)
+        args = self._request_args(op)
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(op.method, url, **args)
+            except httpx.HTTPError as exc:
+                outcome = self._on_exception(op, exc, attempt)
+            else:
+                outcome = self._on_response(op, response, attempt)
+            if outcome.wait is not None:
+                self._sleep(outcome.wait)
+                attempt += 1
+                continue
+            if outcome.error is not None:
+                raise outcome.error
+            return outcome.value
+
+    def _flow(self, flow: Flow[T]) -> T:
+        reply: Any = None
+        while True:
+            try:
+                step = flow.send(reply)
+            except StopIteration as done:
+                result: T = done.value
+                return result
+            if isinstance(step, Pause):
+                self._sleep(step.seconds)
+                reply = None
+            else:
+                reply = self._run(step)
+
+
+class AsyncEngine(Engine):
+    def __init__(self, *args: Any, http_client: Optional[httpx.AsyncClient] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=self._timeout())
+
+    async def close(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self: T) -> T:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def _sleep(self, seconds: float) -> None:
+        if seconds > 0:
+            await asyncio.sleep(seconds)
+
+    async def _run(self, op: Op) -> Any:
+        url = self.settings.url(op.endpoint, op.query, **op.path_params)
+        args = self._request_args(op)
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(op.method, url, **args)
+            except httpx.HTTPError as exc:
+                outcome = self._on_exception(op, exc, attempt)
+            else:
+                outcome = self._on_response(op, response, attempt)
+            if outcome.wait is not None:
+                await self._sleep(outcome.wait)
+                attempt += 1
+                continue
+            if outcome.error is not None:
+                raise outcome.error
+            return outcome.value
+
+    async def _flow(self, flow: Flow[T]) -> T:
+        reply: Any = None
+        while True:
+            try:
+                step = flow.send(reply)
+            except StopIteration as done:
+                result: T = done.value
+                return result
+            if isinstance(step, Pause):
+                await self._sleep(step.seconds)
+                reply = None
+            else:
+                reply = await self._run(step)

fazercards_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

fazercards_sdk/client.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from ._core import AsyncEngine, Op, SyncEngine
+from .models import WebhookEvent
+from .resources import AccountResource, GiftCards, Orders, Steam, Telegram, Topups
+from .webhooks import Payload, header, verify_webhook
+
+
+class _Namespaces:
+    settings: Any
+
+    def _mount(self) -> None:
+        self.account = AccountResource(self)
+        self.topups = Topups(self)
+        self.giftcards = GiftCards(self)
+        self.orders = Orders(self)
+        self.telegram = Telegram(self)
+        self.steam = Steam(self)
+
+    def verify_webhook(self, payload: Payload, signature: str = "", *,
+                       headers: Optional[Mapping[str, Any]] = None) -> WebhookEvent:
+        given = signature or (header(headers) if headers is not None else "")
+        return verify_webhook(self.settings.webhook_secret.get_secret_value(), payload, given)
+
+    @staticmethod
+    def _raw(method: str, path: str, body: Optional[Mapping[str, Any]], safe: Optional[bool],
+             idempotency_key: Optional[str]) -> Op:
+        verb = method.upper()
+        return Op(verb, path if path.startswith("/") else f"/{path}", body=dict(body) if body is not None else None,
+                  safe=verb == "GET" if safe is None else safe, key=idempotency_key)
+
+
+class FazerCards(SyncEngine, _Namespaces):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._mount()
+
+    def balance(self) -> Any:
+        return self.account.balance()
+
+    def request(self, method: str, path: str, body: Optional[Mapping[str, Any]] = None, *,
+                safe: Optional[bool] = None, idempotency_key: Optional[str] = None) -> Any:
+        return self._run(self._raw(method, path, body, safe, idempotency_key))
+
+
+class AsyncFazerCards(AsyncEngine, _Namespaces):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._mount()
+
+    async def balance(self) -> Any:
+        return await self.account.balance()
+
+    async def request(self, method: str, path: str, body: Optional[Mapping[str, Any]] = None, *,
+                      safe: Optional[bool] = None, idempotency_key: Optional[str] = None) -> Any:
+        return await self._run(self._raw(method, path, body, safe, idempotency_key))