beexar 1.0.1__py3-none-any.whl

beexar/__init__.py

@@ -0,0 +1,86 @@
+"""Beexar operator SDK.
+
+Two halves:
+
+* :class:`~beexar.launcher.Client` — the calls you send to Beexar.
+* :class:`~beexar.wallet.WalletServer` — the four callbacks Beexar sends you.
+
+See https://docs.beexar.com for the full contract.
+"""
+
+from __future__ import annotations
+
+from .errors import ApiCode, ApiError, TwirpCode, WalletError, is_funds_related_code
+from .launcher import PRODUCTION_BASE_URL, Client
+from .money import (
+    MAX_CLIENT_DECIMAL_LEN,
+    MAX_SCALE,
+    CURRENCY_PATTERN,
+    Money,
+    MoneyError,
+    is_valid_currency,
+)
+from .signature import SIGNATURE_HEADER, sign, verify
+from .types import (
+    ROUTES,
+    BalanceRequest,
+    BalanceResult,
+    BetWinRequest,
+    BetWinResult,
+    BetWinTransaction,
+    BetWinTransactionResult,
+    FinishRequest,
+    FinishResult,
+    RequestContext,
+    RollbackRequest,
+    RollbackResult,
+    RollbackTransaction,
+    RollbackTransactionResult,
+    Route,
+    WalletHandler,
+)
+from .wallet import MAX_BODY_BYTES, DispatchResponse, WalletServer, route_from_path
+
+#: Stamped at release time from sdk/VERSION. The same number is published for
+#: the Node, PHP, Go and Python SDKs and always means the same contract snapshot.
+__version__ = "1.0.1"
+
+__all__ = [
+    "__version__",
+    "ApiCode",
+    "ApiError",
+    "TwirpCode",
+    "WalletError",
+    "is_funds_related_code",
+    "Client",
+    "PRODUCTION_BASE_URL",
+    "Money",
+    "MoneyError",
+    "MAX_SCALE",
+    "MAX_CLIENT_DECIMAL_LEN",
+    "CURRENCY_PATTERN",
+    "is_valid_currency",
+    "sign",
+    "verify",
+    "SIGNATURE_HEADER",
+    "ROUTES",
+    "Route",
+    "RequestContext",
+    "BalanceRequest",
+    "BalanceResult",
+    "BetWinTransaction",
+    "BetWinRequest",
+    "BetWinTransactionResult",
+    "BetWinResult",
+    "RollbackTransaction",
+    "RollbackRequest",
+    "RollbackTransactionResult",
+    "RollbackResult",
+    "FinishRequest",
+    "FinishResult",
+    "WalletHandler",
+    "WalletServer",
+    "DispatchResponse",
+    "MAX_BODY_BYTES",
+    "route_from_path",
+]

beexar/asgi.py

@@ -0,0 +1,113 @@
+"""Framework bindings: ASGI, FastAPI and Flask.
+
+Each one exists to solve the same problem in that framework's own way — getting
+the SDK the **raw bytes** of the request. The signature is an HMAC over those
+bytes; a framework that parses the JSON and hands you a dict has already
+destroyed them, and no care afterwards can bring them back.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+from .signature import SIGNATURE_HEADER
+from .wallet import WalletServer, route_from_path
+
+__all__ = ["asgi_app", "fastapi_router", "flask_blueprint"]
+
+
+def asgi_app(server: WalletServer) -> Callable[..., Any]:
+    """A bare ASGI application serving the four callbacks.
+
+    Mount it under any prefix; the routes are matched on the path suffix.
+    """
+
+    async def app(scope: Dict[str, Any], receive: Callable[..., Any], send: Callable[..., Any]) -> None:
+        if scope.get("type") != "http":
+            raise RuntimeError("beexar: the wallet app only handles HTTP scopes")
+
+        route = route_from_path(scope.get("path", "/"))
+        if route is None or scope.get("method") != "POST":
+            await _send_json(send, 404, b'{"code":"invalid_argument","msg":"not found",'
+                                        b'"meta":{"api_code":"404","api_message":"not found"}}')
+            return
+
+        # Read the body as bytes. Never decode it here: the bytes are what the
+        # signature covers.
+        body = b""
+        more = True
+        while more:
+            message = await receive()
+            body += message.get("body", b"")
+            more = message.get("more_body", False)
+
+        headers = {k.decode("latin-1").lower(): v.decode("latin-1") for k, v in scope.get("headers", [])}
+        out = server.dispatch(route, body, headers.get(SIGNATURE_HEADER.lower()), headers)
+        await _send_json(send, out.status, out.body)
+
+    return app
+
+
+async def _send_json(send: Callable[..., Any], status: int, body: bytes) -> None:
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status,
+            "headers": [(b"content-type", b"application/json")],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})
+
+
+def fastapi_router(server: WalletServer, prefix: str = "") -> Any:
+    """A FastAPI ``APIRouter`` with the four callbacks.
+
+    The handlers declare ``Request`` and call ``await request.body()`` rather
+    than a typed model. Declaring a model would make Starlette parse the JSON,
+    and the bytes the signature covers would be gone before the SDK ever saw
+    them. Starlette caches the body, so reading it here is safe.
+    """
+    from fastapi import APIRouter, Request, Response  # imported lazily: FastAPI is optional
+
+    router = APIRouter(prefix=prefix)
+
+    def make(route: str) -> Callable[..., Any]:
+        async def endpoint(request: Request) -> Response:
+            body = await request.body()
+            headers = {k.lower(): v for k, v in request.headers.items()}
+            out = server.dispatch(route, body, headers.get(SIGNATURE_HEADER.lower()), headers)
+            return Response(content=out.body, status_code=out.status, media_type="application/json")
+
+        return endpoint
+
+    for route in ("/balance", "/betwin", "/rollback", "/finish"):
+        router.add_api_route(route, make(route), methods=["POST"])
+
+    return router
+
+
+def flask_blueprint(server: WalletServer, name: str = "beexar_wallet", url_prefix: Optional[str] = None) -> Any:
+    """A Flask ``Blueprint`` with the four callbacks.
+
+    Uses ``request.get_data(cache=True)``, which yields ``bytes``.
+    ``get_data(as_text=True)`` re-decodes the body and is the usual way a Flask
+    integration loses its signature.
+    """
+    from flask import Blueprint, Response, request  # imported lazily: Flask is optional
+
+    blueprint = Blueprint(name, __name__, url_prefix=url_prefix)
+
+    def make(route: str) -> Callable[..., Any]:
+        def endpoint() -> Any:
+            body = request.get_data(cache=True)
+            headers = {k.lower(): v for k, v in request.headers.items()}
+            out = server.dispatch(route, body, headers.get(SIGNATURE_HEADER.lower()), headers)
+            return Response(out.body, status=out.status, mimetype="application/json")
+
+        endpoint.__name__ = "beexar" + route.replace("/", "_")
+        return endpoint
+
+    for route in ("/balance", "/betwin", "/rollback", "/finish"):
+        blueprint.add_url_rule(route, view_func=make(route), methods=["POST"])
+
+    return blueprint

beexar/errors.py

@@ -0,0 +1,200 @@
+"""The api_code registry and the two error types this contract uses."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .money import Money
+
+__all__ = ["ApiCode", "TwirpCode", "is_funds_related_code", "WalletError", "ApiError"]
+
+
+class ApiCode:
+    """SoftSwiss API codes, ported verbatim from the platform's own registry.
+
+    Two things about this contract surprise everyone once:
+
+    1. There are only two HTTP statuses (400 and 500) and two ``code`` values
+       (``invalid_argument`` and ``internal``). All meaning lives in
+       ``meta.api_code``. Branch on that, never on the status.
+    2. A signature failure is HTTP 400 with api_code ``403``, not HTTP 403.
+       Answering 403 breaks the contract.
+    """
+
+    INSUFFICIENT_FUNDS = "100"
+    INVALID_PLAYER = "101"
+    BET_LIMIT_REACHED = "105"
+    MAX_BET_EXCEEDED = "106"
+    GAME_FORBIDDEN = "107"
+    PLAYER_DISABLED = "110"
+    COUNTRY_RESTRICTED = "153"
+    CURRENCY_NOT_ALLOWED = "154"
+    FIELD_IMMUTABLE = "155"
+
+    BAD_REQUEST = "400"
+    FORBIDDEN = "403"
+    NOT_FOUND = "404"
+    #: Beexar extension. Return it from /betwin to reject a transaction whose
+    #: id_provider was already rolled back — including a rollback that arrived
+    #: BEFORE the bet it reverses.
+    ALREADY_ROLLED_BACK = "409"
+
+    GAME_NOT_AVAILABLE = "405"
+    CASINO_DISABLED = "410"
+
+    UNKNOWN_ERROR = "500"
+    SERVICE_UNAVAILABLE = "503"
+    REQUEST_TIMEOUT = "504"
+
+
+class TwirpCode:
+    """The only two ``code`` values this contract uses."""
+
+    INVALID_ARGUMENT = "invalid_argument"
+    INTERNAL = "internal"
+
+
+def is_funds_related_code(code: str) -> bool:
+    """Whether an api_code must carry the player's balance in ``meta.balance``.
+
+    The platform will not complain if you omit it — it reads the field with the
+    error swallowed — so the player simply sees a wrong balance. That is exactly
+    why this SDK refuses to build such an error without one.
+    """
+    return code in (ApiCode.INSUFFICIENT_FUNDS, ApiCode.BET_LIMIT_REACHED, ApiCode.MAX_BET_EXCEEDED)
+
+
+class WalletError(Exception):
+    """Raise this from your handler to answer with a specific api_code.
+
+    Anything else you raise becomes an opaque 500 — your message is never echoed
+    to the platform.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        twirp_code: str,
+        api_code: str,
+        message: str,
+        balance: Optional[Money] = None,
+    ) -> None:
+        super().__init__(message)
+        if is_funds_related_code(api_code) and balance is None:
+            raise TypeError(
+                "api_code {} must carry the player's balance; use insufficient_funds(), "
+                "bet_limit_reached() or max_bet_exceeded()".format(api_code)
+            )
+        self.status = status
+        self.twirp_code = twirp_code
+        self.api_code = api_code
+        self.message = message
+        self.balance = balance
+
+    # --- funds-related: the balance is a required argument, by design ------
+
+    @classmethod
+    def insufficient_funds(cls, balance: Money, message: str = "insufficient funds") -> "WalletError":
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.INSUFFICIENT_FUNDS, message, balance)
+
+    @classmethod
+    def bet_limit_reached(cls, balance: Money, message: str = "bet limit reached") -> "WalletError":
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.BET_LIMIT_REACHED, message, balance)
+
+    @classmethod
+    def max_bet_exceeded(cls, balance: Money, message: str = "max bet exceeded") -> "WalletError":
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.MAX_BET_EXCEEDED, message, balance)
+
+    # --- player / request --------------------------------------------------
+
+    @classmethod
+    def invalid_player(cls, message: str = "invalid player") -> "WalletError":
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.INVALID_PLAYER, message)
+
+    @classmethod
+    def player_disabled(cls, message: str = "player is disabled") -> "WalletError":
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.PLAYER_DISABLED, message)
+
+    @classmethod
+    def game_forbidden(cls, message: str = "game is forbidden to the player") -> "WalletError":
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.GAME_FORBIDDEN, message)
+
+    @classmethod
+    def currency_not_allowed(cls, message: str = "currency is not allowed for the player") -> "WalletError":
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.CURRENCY_NOT_ALLOWED, message)
+
+    @classmethod
+    def bad_request(cls, message: str = "bad request") -> "WalletError":
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.BAD_REQUEST, message)
+
+    @classmethod
+    def invalid_signature(cls, message: str = "invalid signature") -> "WalletError":
+        """HTTP 400 with api_code 403 — the wallet contract never answers HTTP 403."""
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.FORBIDDEN, message)
+
+    @classmethod
+    def not_found(cls, message: str = "not found") -> "WalletError":
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.NOT_FOUND, message)
+
+    @classmethod
+    def already_rolled_back(cls, message: str = "action already rolled back") -> "WalletError":
+        """The transaction's ``id_provider`` was already rolled back (tombstoned)."""
+        return cls(400, TwirpCode.INVALID_ARGUMENT, ApiCode.ALREADY_ROLLED_BACK, message)
+
+    # --- server ------------------------------------------------------------
+
+    @classmethod
+    def internal(cls, message: str = "internal error") -> "WalletError":
+        return cls(500, TwirpCode.INTERNAL, ApiCode.UNKNOWN_ERROR, message)
+
+    @classmethod
+    def service_unavailable(cls, message: str = "service unavailable") -> "WalletError":
+        return cls(500, TwirpCode.INTERNAL, ApiCode.SERVICE_UNAVAILABLE, message)
+
+    @classmethod
+    def with_api_code(
+        cls, api_code: str, message: str, balance: Optional[Money] = None
+    ) -> "WalletError":
+        """Escape hatch for an api_code without a dedicated constructor.
+
+        It runs the same balance check, so it cannot be used to bypass it.
+        """
+        status = 500 if api_code.startswith("5") else 400
+        twirp = TwirpCode.INTERNAL if status >= 500 else TwirpCode.INVALID_ARGUMENT
+        return cls(status, twirp, api_code, message, balance)
+
+    def to_envelope(self) -> Dict[str, Any]:
+        meta: Dict[str, str] = {"api_code": self.api_code, "api_message": self.message}
+        if self.balance is not None:
+            meta["balance"] = str(self.balance)
+        return {"code": self.twirp_code, "msg": self.message, "meta": meta}
+
+
+class ApiError(Exception):
+    """An error answer from the Beexar gateway to one of YOUR calls."""
+
+    def __init__(self, http_status: int, code: str, api_code: str, message: str) -> None:
+        super().__init__(message)
+        self.http_status = http_status
+        self.code = code
+        self.api_code = api_code
+        self.api_message = message
+
+    @classmethod
+    def from_envelope(cls, status: int, envelope: Dict[str, Any]) -> "ApiError":
+        meta = envelope.get("meta") if isinstance(envelope.get("meta"), dict) else {}
+        message = meta.get("api_message") or envelope.get("msg") or "unknown error"
+        return cls(
+            status,
+            str(envelope.get("code", TwirpCode.INTERNAL)),
+            str(meta.get("api_code", status)),
+            str(message),
+        )
+
+    def is_retryable(self) -> bool:
+        """5xx only. A 400 on this contract is terminal."""
+        return self.http_status >= 500
+
+    def is_signature_error(self) -> bool:
+        """Keyed on api_code, because the status alone is ambiguous."""
+        return self.api_code == ApiCode.FORBIDDEN

beexar/launcher.py

@@ -0,0 +1,119 @@
+"""The calls you send to Beexar: launch a session, list the catalogue."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from .errors import ApiError
+from .signature import SIGNATURE_HEADER, sign
+
+__all__ = ["Client", "PRODUCTION_BASE_URL"]
+
+PRODUCTION_BASE_URL = "https://gateway.beexar.com"
+
+
+class Client:
+    """Launch sessions and read the catalogue.
+
+    Every POST is signed with ``hex(HMAC-SHA256(body, api_secret))`` over the
+    exact bytes that go on the wire — the body is encoded once, signed, and
+    sent. Encoding twice is how signatures mysteriously stop matching.
+
+    Transport is :mod:`urllib` from the standard library, so the SDK pulls in no
+    HTTP client. Pass ``transport`` to use requests, httpx, or anything else; it
+    receives the final bytes and headers.
+    """
+
+    def __init__(
+        self,
+        casino_id: str,
+        api_secret: str,
+        base_url: str = PRODUCTION_BASE_URL,
+        timeout: float = 10.0,
+        transport: Optional[Any] = None,
+    ) -> None:
+        if not casino_id:
+            raise ValueError("Client: casino_id is required")
+        if not api_secret:
+            raise ValueError("Client: api_secret is required")
+        self._casino_id = casino_id
+        self._api_secret = api_secret
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        # transport(method, url, headers, body) -> (status, response_bytes)
+        self._transport = transport
+
+    def launch_real(self, request: Dict[str, Any]) -> str:
+        """Launch a real-money session and return the URL to embed."""
+        return self._post_signed("/api/v1/softswiss/launcher/real", request)
+
+    def launch_demo(self, request: Dict[str, Any]) -> str:
+        """Launch a demo session on a virtual balance. No wallet callbacks."""
+        return self._post_signed("/api/v1/softswiss/launcher/demo", request)
+
+    def list_games(
+        self, operator: Optional[str] = None, active: Optional[bool] = None
+    ) -> List[Dict[str, Any]]:
+        """The games enabled for your operator. Public — no signature."""
+        query = {"operator": operator or self._casino_id}
+        if active is not None:
+            query["active"] = "true" if active else "false"
+        url = "{}/api/v1/operator/games?{}".format(self._base_url, urllib.parse.urlencode(query))
+
+        status, body = self._send("GET", url, {"Accept": "application/json"}, None)
+        decoded = _decode(body)
+        if status != 200:
+            raise ApiError.from_envelope(status, decoded)
+        games = decoded.get("games") or []
+        return list(games)
+
+    def _post_signed(self, path: str, payload: Dict[str, Any]) -> str:
+        body_dict = dict(payload)
+        body_dict["casino_id"] = self._casino_id
+
+        # Encode ONCE. The signature and the request body are the same bytes, so
+        # they cannot disagree.
+        body = json.dumps(body_dict, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+        status, response = self._send(
+            "POST",
+            self._base_url + path,
+            {
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                SIGNATURE_HEADER: sign(body, self._api_secret),
+            },
+            body,
+        )
+        decoded = _decode(response)
+        if status != 200:
+            raise ApiError.from_envelope(status, decoded)
+        return str(decoded.get("launch_url", ""))
+
+    def _send(
+        self, method: str, url: str, headers: Dict[str, str], body: Optional[bytes]
+    ) -> "tuple[int, bytes]":
+        if self._transport is not None:
+            return self._transport(method, url, headers, body)
+
+        request = urllib.request.Request(url, data=body, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                return response.status, response.read()
+        except urllib.error.HTTPError as error:
+            # A 400 here is an answer, not a transport failure — read it.
+            return error.code, error.read()
+
+
+def _decode(body: bytes) -> Dict[str, Any]:
+    if not body:
+        return {}
+    try:
+        decoded = json.loads(body.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return {"msg": body.decode("utf-8", "replace")}
+    return decoded if isinstance(decoded, dict) else {"msg": str(decoded)}