beexar 1.0.1__tar.gz

beexar-1.0.1/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/

beexar-1.0.1/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to `beexar`. The version is shared across the Beexar SDKs
+for Node, PHP, Go and Python — the same number always means the same contract
+snapshot.
+
+## 1.0.1 — 2026-09-18
+
+No change to the code you consume. The release exists to move publishing onto
+npm's and PyPI's trusted publishing, so no long-lived registry token is stored
+anywhere any more.
+
+## 1.0.0 — 2026-09-18
+
+First public release.
+
+- `Client` — `launch_real`, `launch_demo`, `list_games`, signed with HMAC-SHA256
+  over the exact request bytes.
+- `WalletServer` — the four seamless-wallet callbacks as one pure
+  `dispatch(route, raw_body, signature)`.
+- Bindings for ASGI, FastAPI and Flask, each dealing with that framework's own
+  way of destroying the raw body.
+- `Money` — decimal amounts that cannot be built from a float.
+- `WalletError` — the full api_code registry, with the balance a required
+  argument for codes 100, 105 and 106.
+- No runtime dependencies.

beexar-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beexar
+
+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.

beexar-1.0.1/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: beexar
+Version: 1.0.1
+Summary: Beexar operator SDK — launch game sessions and serve the four seamless-wallet callbacks.
+Project-URL: Documentation, https://docs.beexar.com/tools/sdk-python/
+Project-URL: Source, https://github.com/beexar-games/beexar-python
+Project-URL: Issues, https://github.com/beexar-games/beexar-python/issues
+License: MIT
+License-File: LICENSE
+Keywords: beexar,betwin,casino,game-aggregator,rollback,seamless-wallet,softswiss
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# beexar
+
+Beexar operator SDK for Python. Launch game sessions, and serve the four
+seamless-wallet callbacks the platform calls during play.
+
+**Zero runtime dependencies** — standard library only. Python 3.9+.
+
+```bash
+pip install beexar
+```
+
+Full docs: **https://docs.beexar.com** · OpenAPI: **https://docs.beexar.com/api-reference/**
+
+---
+
+## The integration in one picture
+
+There are two halves, and the second one is the work.
+
+```
+you  ──  POST /api/v1/softswiss/launcher/real  ──▶  Beexar     (Client)
+                                                      │
+player plays                                          │
+                                                      ▼
+your wallet  ◀──  POST /balance /betwin /rollback /finish  ──  Beexar   (WalletServer)
+```
+
+## Half 1 — launching a game
+
+```python
+from beexar import Client
+
+beexar = Client(os.environ["BEEXAR_CASINO_ID"], os.environ["BEEXAR_API_SECRET"])
+
+launch_url = beexar.launch_real({
+    "game": "dice",
+    "account": {"id": "player_123", "currency": "EUR"},
+    "locale": "en",
+})
+# put launch_url in an iframe
+```
+
+`launch_demo()` does the same on a virtual balance and makes no wallet calls.
+`list_games()` returns the catalogue enabled for you.
+
+## Half 2 — serving the wallet
+
+Implement four methods against your ledger. Everything else — signature
+verification, parsing, validation, the error envelope — is handled.
+
+```python
+from beexar import BetWinResult, BetWinTransactionResult, WalletError, WalletServer
+
+class Wallet:
+    def bet_win(self, request, context):
+        with self.db.transaction():  # ONE transaction. See "The boundary".
+            results = []
+            for t in request.transactions:
+                seen = self.lookup(t.id_provider)
+                if seen:
+                    results.append(BetWinTransactionResult(t.id_provider, seen.id))
+                    continue
+                if self.is_rolled_back(t.id_provider):
+                    raise WalletError.already_rolled_back()
+                if t.type == "bet" and self.balance().compare(t.amount) < 0:
+                    raise WalletError.insufficient_funds(self.balance())
+                results.append(BetWinTransactionResult(t.id_provider, self.apply(t)))
+            return BetWinResult(self.round_id(request.round_id), self.balance(), results)
+
+    # … balance(), rollback(), finish()
+
+server = WalletServer(Wallet(), os.environ["BEEXAR_API_SECRET"])
+```
+
+Mount it:
+
+```python
+from beexar.asgi import fastapi_router
+app.include_router(fastapi_router(server, prefix="/wallet"))   # FastAPI
+
+from beexar.asgi import flask_blueprint
+app.register_blueprint(flask_blueprint(server, url_prefix="/wallet"))   # Flask
+
+from beexar.asgi import asgi_app
+application = asgi_app(server)   # bare ASGI
+```
+
+Then point the four callback URLs in the backoffice at
+`https://your-host/wallet/{balance,betwin,rollback,finish}` and run the
+[Integration Test Game](https://docs.beexar.com/guides/testing/) — 29 scenarios
+against your implementation.
+
+A complete, correct wallet you can read in one sitting:
+[`examples/inmemory_wallet.py`](./examples/inmemory_wallet.py). A runnable
+server: [`examples/server.py`](./examples/server.py).
+
+## The raw body — read this one
+
+The signature is an HMAC over the **exact bytes** of the request. If anything
+parses the JSON and serialises it again before the SDK sees it, those bytes are
+gone — key order, escaping and number rendering all change — and no signature
+can ever match again.
+
+| Framework | The trap | What the binding does |
+|---|---|---|
+| FastAPI | declaring a Pydantic model makes Starlette parse the body and you never see bytes | declares `Request`, calls `await request.body()` |
+| Flask | `request.get_data(as_text=True)` re-decodes the body | `request.get_data(cache=True)` → bytes |
+| ASGI | building the body by concatenating decoded chunks corrupts multi-byte characters | concatenates `bytes` |
+
+`dispatch()` refuses a `str` outright — a decode is not always reversible, and
+verifying a lossy copy is worse than failing. When a signature fails and the SDK
+can tell why, the `on_warning` callback receives the reason in plain words.
+
+## Money
+
+Amounts and balances are decimal strings in the currency's main unit — `"0.90"`
+is ninety cents. `Money` cannot be built from a float, raises on `float()`, and
+refuses `+` and `-` so an accidental mix with a number is impossible.
+
+```python
+str(Money.parse("100.00").sub(Money.parse("0.30")))   # "99.70"
+str(Money.from_minor_units(9970, 2))                  # "99.70" from an integer ledger
+```
+
+`"1E2000000000"` and anything past 16 decimals is rejected on shape, before any
+arithmetic touches it.
+
+## Errors
+
+Two HTTP statuses exist on this contract, 400 and 500, and the meaning lives in
+`meta.api_code`. Raise a `WalletError` and the envelope is built for you:
+
+```python
+raise WalletError.insufficient_funds(current_balance)  # 400 / api_code 100
+raise WalletError.already_rolled_back()                # 400 / api_code 409
+raise WalletError.invalid_player()                     # 400 / api_code 101
+```
+
+Codes 100, 105 and 106 **must** carry the player's balance, so those
+constructors take it as a required argument — there is no way to build one
+without it. Anything else you raise becomes an opaque 500 and your message never
+leaves the process.
+
+## The boundary
+
+The SDK does **not** do idempotency or tombstones for you, and it will not
+pretend to. Both have to happen in the same database transaction as the balance
+update, and no library can join your transaction. What you must do:
+
+1. Store every `id_provider` with a unique index, and check it **inside** the
+   transaction that moves the money.
+2. Store the response you returned — a repeat must return the id and balance you
+   gave the first time, not today's.
+3. On rollback, record a tombstone for `original_id_provider` **whether or not**
+   the original exists. Out-of-order delivery is normal; a later `/betwin` for a
+   tombstoned id must be refused with `WalletError.already_rolled_back()`.
+
+Your handler has **15 seconds**. The platform retries 5xx and timeouts for up to
+30 seconds with the same `id_provider`; it does not retry insufficient funds,
+bet limits, bad requests or signature failures.
+
+## Types come from the spec
+
+The dataclasses track the published OpenAPI documents (`openapi/` in this repo).
+`tests/test_contract.py` reads a normalised description of those specs and fails
+if a property the contract declares never reaches your handler.
+
+## License
+
+MIT

beexar-1.0.1/README.md

@@ -0,0 +1,170 @@
+# beexar
+
+Beexar operator SDK for Python. Launch game sessions, and serve the four
+seamless-wallet callbacks the platform calls during play.
+
+**Zero runtime dependencies** — standard library only. Python 3.9+.
+
+```bash
+pip install beexar
+```
+
+Full docs: **https://docs.beexar.com** · OpenAPI: **https://docs.beexar.com/api-reference/**
+
+---
+
+## The integration in one picture
+
+There are two halves, and the second one is the work.
+
+```
+you  ──  POST /api/v1/softswiss/launcher/real  ──▶  Beexar     (Client)
+                                                      │
+player plays                                          │
+                                                      ▼
+your wallet  ◀──  POST /balance /betwin /rollback /finish  ──  Beexar   (WalletServer)
+```
+
+## Half 1 — launching a game
+
+```python
+from beexar import Client
+
+beexar = Client(os.environ["BEEXAR_CASINO_ID"], os.environ["BEEXAR_API_SECRET"])
+
+launch_url = beexar.launch_real({
+    "game": "dice",
+    "account": {"id": "player_123", "currency": "EUR"},
+    "locale": "en",
+})
+# put launch_url in an iframe
+```
+
+`launch_demo()` does the same on a virtual balance and makes no wallet calls.
+`list_games()` returns the catalogue enabled for you.
+
+## Half 2 — serving the wallet
+
+Implement four methods against your ledger. Everything else — signature
+verification, parsing, validation, the error envelope — is handled.
+
+```python
+from beexar import BetWinResult, BetWinTransactionResult, WalletError, WalletServer
+
+class Wallet:
+    def bet_win(self, request, context):
+        with self.db.transaction():  # ONE transaction. See "The boundary".
+            results = []
+            for t in request.transactions:
+                seen = self.lookup(t.id_provider)
+                if seen:
+                    results.append(BetWinTransactionResult(t.id_provider, seen.id))
+                    continue
+                if self.is_rolled_back(t.id_provider):
+                    raise WalletError.already_rolled_back()
+                if t.type == "bet" and self.balance().compare(t.amount) < 0:
+                    raise WalletError.insufficient_funds(self.balance())
+                results.append(BetWinTransactionResult(t.id_provider, self.apply(t)))
+            return BetWinResult(self.round_id(request.round_id), self.balance(), results)
+
+    # … balance(), rollback(), finish()
+
+server = WalletServer(Wallet(), os.environ["BEEXAR_API_SECRET"])
+```
+
+Mount it:
+
+```python
+from beexar.asgi import fastapi_router
+app.include_router(fastapi_router(server, prefix="/wallet"))   # FastAPI
+
+from beexar.asgi import flask_blueprint
+app.register_blueprint(flask_blueprint(server, url_prefix="/wallet"))   # Flask
+
+from beexar.asgi import asgi_app
+application = asgi_app(server)   # bare ASGI
+```
+
+Then point the four callback URLs in the backoffice at
+`https://your-host/wallet/{balance,betwin,rollback,finish}` and run the
+[Integration Test Game](https://docs.beexar.com/guides/testing/) — 29 scenarios
+against your implementation.
+
+A complete, correct wallet you can read in one sitting:
+[`examples/inmemory_wallet.py`](./examples/inmemory_wallet.py). A runnable
+server: [`examples/server.py`](./examples/server.py).
+
+## The raw body — read this one
+
+The signature is an HMAC over the **exact bytes** of the request. If anything
+parses the JSON and serialises it again before the SDK sees it, those bytes are
+gone — key order, escaping and number rendering all change — and no signature
+can ever match again.
+
+| Framework | The trap | What the binding does |
+|---|---|---|
+| FastAPI | declaring a Pydantic model makes Starlette parse the body and you never see bytes | declares `Request`, calls `await request.body()` |
+| Flask | `request.get_data(as_text=True)` re-decodes the body | `request.get_data(cache=True)` → bytes |
+| ASGI | building the body by concatenating decoded chunks corrupts multi-byte characters | concatenates `bytes` |
+
+`dispatch()` refuses a `str` outright — a decode is not always reversible, and
+verifying a lossy copy is worse than failing. When a signature fails and the SDK
+can tell why, the `on_warning` callback receives the reason in plain words.
+
+## Money
+
+Amounts and balances are decimal strings in the currency's main unit — `"0.90"`
+is ninety cents. `Money` cannot be built from a float, raises on `float()`, and
+refuses `+` and `-` so an accidental mix with a number is impossible.
+
+```python
+str(Money.parse("100.00").sub(Money.parse("0.30")))   # "99.70"
+str(Money.from_minor_units(9970, 2))                  # "99.70" from an integer ledger
+```
+
+`"1E2000000000"` and anything past 16 decimals is rejected on shape, before any
+arithmetic touches it.
+
+## Errors
+
+Two HTTP statuses exist on this contract, 400 and 500, and the meaning lives in
+`meta.api_code`. Raise a `WalletError` and the envelope is built for you:
+
+```python
+raise WalletError.insufficient_funds(current_balance)  # 400 / api_code 100
+raise WalletError.already_rolled_back()                # 400 / api_code 409
+raise WalletError.invalid_player()                     # 400 / api_code 101
+```
+
+Codes 100, 105 and 106 **must** carry the player's balance, so those
+constructors take it as a required argument — there is no way to build one
+without it. Anything else you raise becomes an opaque 500 and your message never
+leaves the process.
+
+## The boundary
+
+The SDK does **not** do idempotency or tombstones for you, and it will not
+pretend to. Both have to happen in the same database transaction as the balance
+update, and no library can join your transaction. What you must do:
+
+1. Store every `id_provider` with a unique index, and check it **inside** the
+   transaction that moves the money.
+2. Store the response you returned — a repeat must return the id and balance you
+   gave the first time, not today's.
+3. On rollback, record a tombstone for `original_id_provider` **whether or not**
+   the original exists. Out-of-order delivery is normal; a later `/betwin` for a
+   tombstoned id must be refused with `WalletError.already_rolled_back()`.
+
+Your handler has **15 seconds**. The platform retries 5xx and timeouts for up to
+30 seconds with the same `id_provider`; it does not retry insufficient funds,
+bet limits, bad requests or signature failures.
+
+## Types come from the spec
+
+The dataclasses track the published OpenAPI documents (`openapi/` in this repo).
+`tests/test_contract.py` reads a normalised description of those specs and fails
+if a property the contract declares never reaches your handler.
+
+## License
+
+MIT

beexar-1.0.1/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-1.0.1/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