@clovnet/casino-sdk 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,148 @@
+# @clovnet/casino-sdk
+
+[![CI](https://github.com/casinowebengine/casino-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/casinowebengine/casino-sdk/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@clovnet/casino-sdk.svg)](https://www.npmjs.com/package/@clovnet/casino-sdk)
+[![types](https://img.shields.io/npm/types/@clovnet/casino-sdk.svg)](https://www.npmjs.com/package/@clovnet/casino-sdk)
+
+The **player / casino frontend SDK** for the [CasinoWebEngine](https://github.com/casinowebengine) Runtime
+Core. It wraps everything a player can do — auth, cashier, wallet, catalog, real game launch, and live
+realtime updates — and hides the cross-cutting concerns (cookie session, CSRF, tenant header, idempotency
+keys, reconnect, dedupe) so your frontend never thinks about them.
+
+- **Framework-agnostic core** + optional **React bindings** (`/react`) and a standalone **realtime client** (`/realtime`).
+- **Isomorphic**: browser, Node, and Next.js (SSR/RSC-safe — realtime is client-only).
+- **Fully typed** end-to-end, dual **ESM + CJS**, tree-shakeable, zero secrets.
+- Money is **integer minor units** with `formatMoney` display helpers.
+
+> The SDK talks to the runtime over the network (`baseUrl` / `wsUrl`). It is **not** a code dependency of
+> the runtime — it is the player HTTP/WS contract, typed.
+
+## Install
+
+```bash
+pnpm add @clovnet/casino-sdk
+# React bindings need react as a peer; Node realtime needs ws:
+pnpm add react ws
+```
+
+## Quickstart (login → deposit → lobby → launch → live balance)
+
+```ts
+import { createCasinoClient, formatMoney } from "@clovnet/casino-sdk";
+
+const sdk = createCasinoClient({
+  baseUrl: "https://api.staging.example",
+  wsUrl: "wss://api.staging.example/realtime",
+  tenantId: "grandbet",
+  realtime: {
+    // Re-read authoritative state after every (re)connect — the socket accelerates, REST is truth.
+    resync: async () => {
+      const b = await sdk.wallet.getBalance();
+      console.log("balance", formatMoney(b.cash, b.currency));
+    },
+  },
+});
+
+// 1. Authenticate (cookie session; CSRF + tenant handled for you)
+await sdk.auth.login({ email: "player@example.com", password: "secret123" });
+
+// 2. Deposit (amounts in scale-4 minor units; idempotency key auto-generated)
+await sdk.cashier.deposit({ amount: 500_000 /* €50.00 */ });
+
+// 3. Lobby (geo/currency-aware)
+const { games } = await sdk.catalog.lobby({ country: "DE", limit: 24 });
+
+// 4. Open a game session with a tenant-registered provider adapter → render the URL in an iframe
+const { launchUrl } = await sdk.games.providerSession("fake", games[0]!.id);
+
+// 5. Live balance over the realtime gateway
+await sdk.realtime.connect();
+sdk.realtime.on("wallet.balance", (e) => {
+  console.log("live balance", formatMoney(e.data.balances.cash, e.data.currency));
+});
+```
+
+### React
+
+```tsx
+"use client";
+import {
+  CasinoProvider,
+  useAuth,
+  useBalance,
+  useLobby,
+  useGameLaunch,
+} from "@clovnet/casino-sdk/react";
+import { createCasinoClient, formatMoney } from "@clovnet/casino-sdk";
+
+const sdk = createCasinoClient({ baseUrl, wsUrl, tenantId: "grandbet" });
+
+export default function App() {
+  return (
+    <CasinoProvider client={sdk}>
+      <Wallet />
+    </CasinoProvider>
+  );
+}
+
+function Wallet() {
+  const { player } = useAuth();
+  const { data: balance, connection } = useBalance(); // live, realtime-backed
+  return (
+    <div>
+      {player?.email} — {balance && formatMoney(balance.cash, balance.currency)} ({connection})
+    </div>
+  );
+}
+```
+
+### Plugin actions (`sdk.ext`)
+
+Tenant-enabled plugins expose player-facing actions on the casino API. Discover them and call them with
+the same DX as core modules — no build-time knowledge needed:
+
+```ts
+// Discovery (cached; ETag-revalidated)
+const { plugins } = await sdk.ext.catalog();
+
+// Generic — works for any enabled plugin:
+const summary = await sdk.ext("cashback").call("getSummary");
+await sdk.ext("cashback").call("claim", { periodId }); // idempotency key auto-generated
+
+// Typed — when the plugin's generated client package is installed, its ExtRegistry
+// augmentation narrows call() keys, input, and result:
+import { cashback } from "@cwe-plugins/cashback-client";
+const res = await cashback(sdk).claim({ periodId });
+
+// Live plugin events
+sdk.realtime.on("ext.cashback", (e) => console.log(e.data.type, e.data.payload));
+```
+
+React: `useExtCatalog()`, `useExtQuery(pluginKey, actionKey, input?, { refetchOn })`,
+`useExtAction(pluginKey, actionKey)`.
+
+## Modules
+
+| Module          | What                                                                                                                                        |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sdk.auth`      | signup, login, logout, refresh, me, social OAuth, sessions ("your devices"), password reset/change, email/phone verification, login history |
+| `sdk.cashier`   | deposit, withdraw, payment methods, deposit/withdrawal history + status, cancel withdrawal                                                  |
+| `sdk.wallet`    | balance buckets (cash/bonus/locked), transaction history, ledger                                                                            |
+| `sdk.catalog`   | lobby, search, categories tree, providers, game detail, suggested, trending                                                                 |
+| `sdk.games`     | provider game sessions → `{ launchUrl, sessionId }` (https-validated), bet + game-session history                                           |
+| `sdk.realtime`  | ticket handshake → WS; channels `wallet.balance`/`deposit`/`withdrawal`, `gaming`, `bonus`, `player`, `ext.<pluginKey>`                     |
+| `sdk.player`    | profile, preferences, consents, responsible-gaming limits + cool-off/self-exclusion, account close / GDPR export                            |
+| `sdk.kyc`       | KYC status, requirements, history, document upload (multipart), submit                                                                      |
+| `sdk.affiliate` | public click tracking → `clickId` join key for signup attribution                                                                           |
+| `sdk.ext`       | plugin actions: catalog discovery + `ext(pluginKey).call(actionKey, input)`; typed via `ExtRegistry` augmentation                           |
+
+## Documentation
+
+- [`docs/SDK_BIBLE.md`](docs/SDK_BIBLE.md) — the SDK's source of truth (design, auth/CSRF, realtime, errors, money, versioning, publishing, endpoint map).
+- [`docs/guides/`](docs/guides) — per-module guides.
+- API reference: `pnpm docs` (TypeDoc → `docs/api`).
+- Local development & linking: [`docs/guides/linking.md`](docs/guides/linking.md).
+
+## License
+
+MIT