@cwe-dev/casino-sdk

The player / casino frontend SDK for the 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

pnpm add @cwe-dev/casino-sdk
# React bindings need react as a peer; Node realtime needs ws:
pnpm add react ws

Quickstart (login → deposit → lobby → launch → live balance)

import { createCasinoClient, formatMoney } from "@cwe-dev/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: "[email protected]", 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. Launch a real SlotServ game → render the returned URL in an iframe
const { launchUrl } = await sdk.games.launch(games[0]!.id, { device: "desktop", mode: "real" });

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

"use client";
import {
  CasinoProvider,
  useAuth,
  useBalance,
  useLobby,
  useGameLaunch,
} from "@cwe-dev/casino-sdk/react";
import { createCasinoClient, formatMoney } from "@cwe-dev/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:

// 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 | launch a real SlotServ game → { launchUrl, sessionId } (https-validated), provider sessions, 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 — the SDK's source of truth (design, auth/CSRF, realtime, errors, money, versioning, publishing, endpoint map).
• docs/guides/ — per-module guides.
• API reference: pnpm docs (TypeDoc → docs/api).
• Local development & linking: docs/guides/linking.md.

License

MIT