@clovnet/casino-sdk 1.0.0

package/dist/client-B3-Y0Xan.d.cts

@@ -0,0 +1,2167 @@
+import { j as WebSocketImpl, a as ConnectionState, d as RealtimeChannel, C as ChannelEventMap, U as Unsubscribe, e as RealtimeError } from './contract-DtFe4bRy.cjs';
+
+/**
+ * Plugin-actions (ext) transport contract — mirrored verbatim from the runtime's
+ * frozen plugin-actions wire contract (see `docs/CASINO_SDK_EXT_BUILD_PROMPT.md` §2,
+ * built in the runtime repo from `PLUGIN_ACTIONS_RUNTIME_BUILD_PROMPT.md`).
+ *
+ * Discovery endpoints:
+ *
+ * ```
+ * GET /api/ext/_catalog             → ExtCatalog          (ETag + Cache-Control: max-age=60)
+ * GET /api/ext/_catalog/:pluginKey  → ExtCatalogPlugin    (404 if plugin not enabled for tenant)
+ * ```
+ *
+ * Action calls are plain HTTP to `PluginActionDescriptor.path` over the SDK's
+ * standard transport. Plugin payloads are opaque to the SDK — no minor-unit money
+ * conversion happens on `ext` responses; consult each plugin's docs for its shapes.
+ *
+ * This file also hosts the typed-client machinery ({@link ExtRegistry} and friends)
+ * used by generated `@cwe-plugins/<key>-client` packages. It is types-only so the
+ * error model can reference {@link ExtPluginClient} without import cycles.
+ */
+interface ExtCatalog {
+    catalogVersion: 1;
+    tenantId: string;
+    plugins: ExtCatalogPlugin[];
+}
+interface ExtCatalogPlugin {
+    pluginKey: string;
+    /** Installed plugin semver. */
+    version: string;
+    title: string;
+    actions: PluginActionDescriptor[];
+    /** Realtime channels the plugin may publish, e.g. `["ext.cashback"]`. */
+    channels: string[];
+    /** Optional widget descriptors. */
+    frontend?: PluginFrontendDecl;
+}
+interface PluginActionDescriptor {
+    key: string;
+    title: string;
+    description?: string;
+    kind: "query" | "mutation";
+    /** Mutation requires an `Idempotency-Key` header (auto-generated if absent). */
+    idempotent?: boolean;
+    deprecated?: string;
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    /** Absolute, e.g. `"/api/ext/cashback/claim"`. */
+    path: string;
+    /** `"player"` ⇒ session cookie required (the SDK handles this as usual). */
+    auth: "public" | "player";
+    /** JSON Schema draft-07 for params/query/body. */
+    input?: unknown;
+    /** JSON Schema, when declared. */
+    output?: unknown;
+    /** Plugin event types this action may cause. */
+    emits?: string[];
+}
+interface PluginFrontendDecl {
+    widgets?: Array<{
+        key: string;
+        title: string;
+        slot: "lobby" | "account" | "cashier" | "game-sidebar";
+        /** A `kind: "query"` action key. */
+        dataAction: string;
+        /** Mutation action keys. */
+        actions?: string[];
+    }>;
+}
+/** HTTP methods a plugin action may declare. */
+type ExtMethod = "GET" | "POST" | "PUT" | "DELETE";
+interface ExtCallOpts {
+    /** Use this idempotency key instead of an auto-generated one. */
+    idempotencyKey?: string;
+    /** Abort signal. */
+    signal?: AbortSignal;
+}
+/** Init for the {@link ExtPluginClient.request} escape hatch. */
+interface ExtRequestInit extends ExtCallOpts {
+    /** Query params; `undefined`/`null` are dropped, arrays repeat the key. */
+    query?: Record<string, unknown>;
+    /** JSON body (plugins validate `.strict()` — send exactly the declared keys). */
+    body?: unknown;
+}
+/**
+ * Lazy per-plugin handle returned by `sdk.ext(pluginKey)`. Nothing is fetched
+ * until `call()`/`request()` is used.
+ */
+interface ExtPluginClient {
+    /** The plugin this handle targets. */
+    readonly pluginKey: string;
+    /**
+     * Call a catalog-declared action. Resolves the action descriptor from the
+     * (cached) catalog, routes `input` per the action's method, and auto-generates
+     * an `Idempotency-Key` for idempotent mutations.
+     */
+    call<TResult = unknown>(actionKey: string, input?: unknown, opts?: ExtCallOpts): Promise<TResult>;
+    /**
+     * Escape hatch for declared routes not in the catalog (same transport, no
+     * descriptor lookup). `path` is relative to the plugin mount:
+     * `request("GET", "/games/starburst")` → `GET /api/ext/<pluginKey>/games/starburst`.
+     */
+    request<TResult = unknown>(method: ExtMethod, path: string, init?: ExtRequestInit): Promise<TResult>;
+}
+/**
+ * Per-action shape a generated client declares: `input` (omit for none) and
+ * `output` (omit for `unknown`).
+ */
+interface ExtActionShape {
+    input?: unknown;
+    output?: unknown;
+}
+/**
+ * Augmentation point for generated plugin clients. Empty by default; a generated
+ * package adds its plugin under its key:
+ *
+ * ```ts
+ * declare module "@clovnet/casino-sdk" {
+ *   interface ExtRegistry {
+ *     cashback: {
+ *       getSummary: { output: CashbackSummary };
+ *       claim: { input: { periodId: string }; output: ClaimResult };
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * With that in scope, `sdk.ext("cashback")` returns a {@link TypedExtPluginClient}
+ * whose `call()` narrows action keys, input, and result. Unregistered plugin keys
+ * keep the loosely-typed {@link ExtPluginClient}.
+ */
+interface ExtRegistry {
+}
+/** The declared input type of an action shape (`undefined` when it takes none; an optional `input?:` admits `undefined`). */
+type ExtActionInput<S> = "input" extends keyof S ? S extends {
+    input?: infer I;
+} ? {} extends Pick<S, "input" & keyof S> ? I | undefined : I : never : undefined;
+/** The declared output type of an action shape (`unknown` when undeclared). */
+type ExtActionOutput<S> = "output" extends keyof S ? S extends {
+    output?: infer O;
+} ? O : never : unknown;
+/** `call()` argument tuple for an action shape: input is optional only when it may be omitted. */
+type ExtCallArgs<S> = [ExtActionInput<S>] extends [undefined] ? [input?: undefined, opts?: ExtCallOpts] : undefined extends ExtActionInput<S> ? [input?: ExtActionInput<S>, opts?: ExtCallOpts] : [input: ExtActionInput<S>, opts?: ExtCallOpts];
+/**
+ * The narrowed handle `sdk.ext(pluginKey)` returns when `pluginKey` is registered
+ * in {@link ExtRegistry}. Transport is identical to {@link ExtPluginClient} — this
+ * is typing only.
+ */
+interface TypedExtPluginClient<A> {
+    readonly pluginKey: string;
+    call<K extends keyof A & string>(actionKey: K, ...args: ExtCallArgs<A[K]>): Promise<ExtActionOutput<A[K]>>;
+    request<TResult = unknown>(method: ExtMethod, path: string, init?: ExtRequestInit): Promise<TResult>;
+}
+
+/**
+ * Error model.
+ *
+ * The runtime returns a single envelope shape on failure:
+ *
+ * ```json
+ * { "error": { "code": "INSUFFICIENT_FUNDS", "message": "...", "details": { } } }
+ * ```
+ *
+ * `mapEnvelope` turns that (plus the HTTP status) into a typed {@link CasinoSdkError}
+ * subclass so app code can `instanceof`-branch instead of string-matching codes.
+ */
+
+/** The runtime's `AppError` envelope, as seen on the wire. */
+interface AppErrorEnvelope {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/** Type guard for the runtime error envelope. */
+declare function isAppErrorEnvelope(value: unknown): value is AppErrorEnvelope;
+/**
+ * Base class for every error the SDK throws. Carries the stable machine-readable
+ * `code`, the HTTP `status` (0 for transport/client-side failures), and the
+ * runtime's `details` payload when present.
+ */
+declare class CasinoSdkError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown;
+    constructor(code: string, message: string, status?: number, details?: unknown);
+}
+/** 401 — session missing/invalid/expired. Often triggers an auto-refresh + retry. */
+declare class AuthError extends CasinoSdkError {
+}
+/**
+ * 403 — authenticated but not allowed. This includes CSRF double-submit failures:
+ * the runtime throws them as a plain `FORBIDDEN` (see `packages/core/src/csrf.ts`
+ * in the runtime), so there is deliberately no separate CSRF error class here.
+ */
+declare class ForbiddenError extends CasinoSdkError {
+}
+/** 400 — request failed validation. `details.issues` lists the per-field problems. */
+declare class ValidationError extends CasinoSdkError {
+}
+/** 404 — resource not found. */
+declare class NotFoundError extends CasinoSdkError {
+}
+/** 409 — conflict or invalid state transition. */
+declare class ConflictError extends CasinoSdkError {
+}
+/** 422 — wallet balance too low for the requested debit (`INSUFFICIENT_FUNDS`). */
+declare class InsufficientFundsError extends CasinoSdkError {
+}
+/**
+ * 422 — the request was semantically rejected and no more-specific domain code
+ * matched. The neutral fallback for unknown 422s: a future non-money 422 must not
+ * `instanceof`-match app branches written for insufficient funds.
+ */
+declare class UnprocessableError extends CasinoSdkError {
+}
+/**
+ * 422 — a cashier gate plugin denied the operation (`DEPOSIT_DENIED`,
+ * `WITHDRAWAL_DENIED`, `DEPOSIT_LIMIT_EXCEEDED`, `WITHDRAWAL_LIMIT_EXCEEDED`).
+ * `details.pluginId` names the deciding plugin.
+ */
+declare class OperationDeniedError extends CasinoSdkError {
+}
+/**
+ * 429 — rate limited. On verification-request cooldowns `details.resendIn`
+ * gives the seconds to wait before retrying.
+ */
+declare class RateLimitError extends CasinoSdkError {
+}
+/**
+ * 409 `FLOW_DELEGATED` — this tenant delegates the flow (signup/deposit/
+ * withdrawal/KYC) to a plugin; drive the plugin's actions via `sdk.ext`
+ * instead. `details: { flow, pluginKey }`.
+ */
+declare class FlowDelegatedError extends ConflictError {
+    /** The plugin that owns the delegated flow (from `details.pluginKey`). */
+    readonly pluginKey: string;
+    /** The delegated flow kind (from `details.flow`), e.g. `"deposit"`. */
+    readonly flow: string | undefined;
+    /**
+     * Set (best-effort, by the SDK) when the ext catalog shows an action named
+     * after the flow — `sdk.ext(pluginKey).call(continueWith.actionKey, …)` is
+     * then the way to continue. Left `undefined` when the catalog lookup fails;
+     * the original error is never masked.
+     */
+    continueWith?: {
+        actionKey: string;
+    };
+    constructor(code: string, message: string, status?: number, details?: unknown);
+    /** Sugar for `sdk.ext(this.pluginKey)` — the plugin client to continue the flow with. */
+    resolve(sdk: {
+        ext: (pluginKey: string) => ExtPluginClient;
+    }): ExtPluginClient;
+}
+/**
+ * 409 `RG_BLOCKED` — a responsible-gaming state blocks the operation.
+ * `details: { reason: "cool_off" | "self_excluded", until: string | null }`.
+ */
+declare class RgBlockedError extends CasinoSdkError {
+}
+/**
+ * 409 `LIMIT_EXCEEDED` — a responsible-gaming limit blocks the operation.
+ * `details: { kind, period, remainingMinor, resetsAt }`.
+ */
+declare class LimitExceededError extends CasinoSdkError {
+}
+/** 5xx — the runtime failed internally. */
+declare class ServerError extends CasinoSdkError {
+}
+/** No HTTP response (DNS/offline/abort/CORS). `status` is 0. */
+declare class NetworkError extends CasinoSdkError {
+}
+/**
+ * A capability the SDK exposes for surface-completeness, but the runtime does not
+ * implement yet. See the roadmap in `docs/SDK_BIBLE.md`.
+ */
+declare class NotImplementedError extends CasinoSdkError {
+    constructor(message: string);
+}
+/**
+ * The plugin is not installed/enabled for this tenant — either a 404 from an
+ * `/api/ext/*` route (the runtime makes disabled and not-installed
+ * indistinguishable) or the plugin is absent from a fresh catalog (then thrown
+ * client-side with `status` 0 and code `PLUGIN_NOT_ENABLED`, no network call).
+ */
+declare class PluginNotEnabledError extends NotFoundError {
+    readonly pluginKey: string;
+    constructor(pluginKey: string, options?: {
+        code?: string;
+        message?: string;
+        status?: number;
+        details?: unknown;
+    });
+}
+/**
+ * The action key is not among the plugin's catalog descriptors. Thrown
+ * client-side (status 0) without a network call when the catalog is fresh.
+ */
+declare class PluginActionNotFoundError extends NotFoundError {
+    readonly pluginKey: string;
+    readonly actionKey: string;
+    constructor(pluginKey: string, actionKey: string);
+}
+/**
+ * The plugin handler timed out or crashed — a 504 from an `/api/ext/*` route or
+ * the envelope code `PLUGIN_ROUTE_ERROR` (also the legacy `PLUGIN_ROUTE_TIMEOUT`).
+ */
+declare class PluginUnavailableError extends ServerError {
+}
+/**
+ * A generated plugin client's expected major version does not match the
+ * installed plugin's version in the catalog. Thrown client-side by
+ * `assertPluginVersion` (status 0).
+ */
+declare class PluginVersionMismatchError extends ConflictError {
+    readonly pluginKey: string;
+    readonly expectedRange: string;
+    readonly actualVersion: string;
+    constructor(pluginKey: string, expectedRange: string, actualVersion: string);
+}
+
+/** Minimal cookie store used when no browser cookie jar exists. */
+declare class CookieJar {
+    private readonly store;
+    /** Read a cookie value by name, or undefined. */
+    get(name: string): string | undefined;
+    /** Serialize all cookies into a `Cookie` request-header value. */
+    header(): string | undefined;
+    /** Clear the jar (e.g. on logout). */
+    clear(): void;
+    /**
+     * Ingest `set-cookie` header(s) from a response. Only the `name=value` pair is
+     * retained (attributes like Path/HttpOnly are ignored — this jar is a dev/SSR
+     * convenience, not a spec-complete cookie store). A `Max-Age<=0` or an `Expires`
+     * in the past deletes the cookie; `Max-Age` wins when both are present.
+     */
+    ingest(setCookie: string | string[] | null | undefined): void;
+}
+
+/**
+ * Client configuration.
+ */
+
+/** A `fetch`-compatible function. Defaults to the platform global. */
+type FetchLike = typeof fetch;
+/** Cookie names the runtime sets. Stable; surfaced for advanced use. */
+declare const COOKIE: {
+    readonly access: "cwe_access_token";
+    readonly refresh: "cwe_refresh_token";
+    readonly csrf: "cwe_csrf";
+};
+/** Header names the SDK sends. */
+declare const HEADER: {
+    readonly tenant: "x-tenant-id";
+    readonly brand: "x-brand-id";
+    readonly region: "x-region";
+    readonly csrf: "x-csrf-token";
+    readonly idempotency: "idempotency-key";
+};
+interface CasinoClientConfig {
+    /** Base URL of the runtime HTTP API, e.g. `https://api.staging.example`. */
+    baseUrl: string;
+    /**
+     * WebSocket URL of the realtime gateway, e.g. `wss://api.staging.example/realtime`.
+     * Optional — only needed if you use `sdk.realtime`. Defaults to `baseUrl` with
+     * the protocol swapped to ws(s) and `/realtime` appended.
+     */
+    wsUrl?: string;
+    /**
+     * Tenant id sent as `x-tenant-id` on every request — as *declared intent*,
+     * not as the selector. Since the runtime's H1 trusted tenant resolution, the
+     * tenant is determined by the request host (`baseUrl`'s origin → the
+     * runtime's trusted host→tenant map, else its env base); an untrusted
+     * `x-tenant-id` is ignored. The header is only honored when a trusted
+     * internal proxy forwards it with `x-internal-tenant-token`. Point `baseUrl`
+     * at the correct brand host; multi-brand apps need one client per brand
+     * base URL.
+     */
+    tenantId: string;
+    /** Optional brand id sent as `x-brand-id`. */
+    brandId?: string;
+    /** Optional region sent as `x-region`. */
+    region?: string;
+    /** Default fiat currency for wallet/cashier/launch calls (ISO 4217). Default `EUR`. */
+    defaultCurrency?: string;
+    /** Injected fetch (Node < 18, tests, custom agents). Defaults to global `fetch`. */
+    fetch?: FetchLike;
+    /**
+     * Called when a request fails auth even after one refresh attempt. Use it to
+     * route the user to login / clear app state. Receives the originating error.
+     */
+    onAuthError?: (error: CasinoSdkError) => void;
+    /**
+     * Disable the automatic 401 → refresh → retry behavior (default enabled).
+     * Turn off if you manage refresh yourself.
+     */
+    autoRefresh?: boolean;
+    /**
+     * Node/SSR only: the cookie jar this client reads and writes (the browser manages
+     * its own cookies). Defaults to a fresh private jar. On a server that handles many
+     * users, never share one jar (or one module-scope client) across requests — use
+     * `client.withCookies(new CookieJar())` per incoming request instead.
+     */
+    cookieJar?: CookieJar;
+    /**
+     * Default per-request timeout in milliseconds — a black-holed request rejects
+     * with `NetworkError` (code `NETWORK_TIMEOUT`) instead of hanging forever, so
+     * `deposit()`/`withdraw()`/`login()` always settle. Default 30 000; `0` disables.
+     * Calls that legitimately run long expose a per-call override — e.g.
+     * `kyc.uploadDocument(input, { timeoutMs })` for large files on slow uplinks.
+     */
+    timeoutMs?: number;
+}
+/** Internal, fully-resolved config with defaults applied. */
+interface ResolvedConfig extends Required<Omit<CasinoClientConfig, "brandId" | "region" | "onAuthError" | "cookieJar">> {
+    brandId: string | undefined;
+    region: string | undefined;
+    onAuthError: ((error: CasinoSdkError) => void) | undefined;
+    cookieJar: CookieJar | undefined;
+}
+
+/**
+ * The isomorphic HTTP layer every module calls through.
+ *
+ * Responsibilities (so modules and app code never deal with them):
+ * - inject `x-tenant-id` (+ optional brand/region) from config — declared intent
+ *   only: the runtime resolves the tenant from the request host (H1) and ignores
+ *   untrusted `x-tenant-*` headers,
+ * - `credentials: "include"` for the cookie session; in Node, replay/ingest a
+ *   {@link CookieJar},
+ * - double-submit CSRF: read `cwe_csrf`, send `x-csrf-token` on mutations,
+ * - auto idempotency keys for money ops (body field + header),
+ * - decode the `AppError` envelope into a typed {@link CasinoSdkError},
+ * - on 401, attempt a single refresh + retry, then fire `onAuthError` — the refresh
+ *   is single-flight across concurrent 401s and never refreshes itself,
+ * - apply the default request timeout (`timeoutMs`, 30s) → `NETWORK_TIMEOUT`.
+ */
+
+type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface RequestOptions {
+    /** Query params; `undefined`/`null` are dropped, arrays repeat the key. */
+    query?: Record<string, string | number | boolean | undefined | null | readonly string[]>;
+    /**
+     * Request body. A plain value is JSON-encoded; a `FormData` is sent as
+     * multipart (content-type left to fetch so the boundary is set) — used by
+     * KYC document uploads.
+     */
+    body?: unknown;
+    /**
+     * Mark this a money operation: the SDK injects an idempotency key into both the
+     * body (`idempotencyKey`) and the `idempotency-key` header.
+     */
+    idempotent?: boolean;
+    /** Provide your own idempotency key instead of an auto-generated one. */
+    idempotencyKey?: string;
+    /**
+     * With `idempotent`, send the key as the `idempotency-key` header only and leave
+     * the body untouched. Plugin ext routes validate bodies `.strict()` and read the
+     * key from the header, so an injected body field would be rejected.
+     */
+    idempotencyHeaderOnly?: boolean;
+    /** Force-enable/disable the CSRF header (defaults: on for mutations). */
+    csrf?: boolean;
+    /** Extra request headers, merged after the SDK's own (advanced; e.g. `if-none-match`). */
+    headers?: Record<string, string>;
+    /** Abort signal. */
+    signal?: AbortSignal;
+    /** Per-request timeout in ms, overriding `config.timeoutMs` (`0` disables). */
+    timeoutMs?: number;
+    /** Internal: prevents infinite refresh recursion. */
+    _isRetry?: boolean;
+    /**
+     * Internal: this request must never enter the 401 → refresh → retry path, and a
+     * 401 on it does not fire `onAuthError` itself. Set on the refresh POST: when
+     * refresh 401s (fully logged out), the *originating* request reports the auth
+     * failure exactly once instead of the refresh request recursing into itself.
+     */
+    _noRefresh?: boolean;
+    /**
+     * Internal: skip the error enricher for this request. Set on the ext catalog
+     * reads the enricher itself performs, so an erroring catalog can never
+     * re-enter its own error path.
+     */
+    _noEnrich?: boolean;
+}
+/** Result of a {@link HttpClient.conditionalGet} (ETag revalidation). */
+interface ConditionalGetResult<T> {
+    /** True when the server answered `304 Not Modified` — keep your cached copy. */
+    notModified: boolean;
+    /** The parsed body (present on 2xx, absent on 304). */
+    data?: T;
+    /** The response `ETag`, to send back as `etag` on the next call. */
+    etag?: string;
+    /** Parsed `Cache-Control: max-age=N`, in seconds. */
+    maxAgeSeconds?: number;
+}
+declare class HttpClient {
+    private readonly config;
+    readonly jar: CookieJar;
+    private refresh;
+    private refreshInflight;
+    private enrich;
+    constructor(config: ResolvedConfig);
+    /** Wired by the client after the auth module exists (avoids a circular import). */
+    setRefreshHandler(fn: () => Promise<void>): void;
+    /**
+     * Wired by the client: a best-effort pass over every decoded error before it is
+     * thrown (e.g. populating `FlowDelegatedError.continueWith` from the ext
+     * catalog). Whatever it does or throws, the original error is what propagates.
+     */
+    setErrorEnricher(fn: (error: CasinoSdkError) => Promise<void> | void): void;
+    get<T>(path: string, options?: Omit<RequestOptions, "body">): Promise<T>;
+    post<T>(path: string, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    request<T>(method: Method, path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * GET with ETag revalidation: sends `If-None-Match` when `etag` is given and
+     * treats `304 Not Modified` as success (empty `data`). Used for endpoints that
+     * declare HTTP caching, e.g. the ext plugin catalog.
+     */
+    conditionalGet<T>(path: string, options?: {
+        etag?: string;
+        signal?: AbortSignal;
+        _noEnrich?: boolean;
+    }): Promise<ConditionalGetResult<T>>;
+    /** The shared pipeline: headers, CSRF, idempotency, cookies, fetch, 401→refresh→retry. */
+    private performFetch;
+    /**
+     * Run the wired refresh handler with single-flight dedupe (same pattern as the
+     * ext catalog): concurrent 401s all await ONE in-flight `POST /auth/player/refresh`.
+     * With rotating refresh tokens, parallel refreshes would present an already-rotated
+     * token and get the whole session revoked.
+     */
+    private runRefresh;
+    private parseBody;
+    private toError;
+    private buildUrl;
+}
+
+/**
+ * Money.
+ *
+ * The runtime keeps money to **4 decimal places** (`@cwe/shared/money.ts`, `SCALE=4`).
+ * Three encodings appear on the wire and the SDK reconciles them to ONE:
+ *
+ * - REST **responses** carry 4-dp **decimal strings** — `"12.5000"`.
+ * - REST **request bodies** take plain JSON **numbers** in major units — `12.5`
+ *   (the runtime's Zod schemas are `z.number()`; it normalizes to 4-dp internally).
+ * - Realtime carries the same value as a **scale-4 integer** — `125000`.
+ *
+ * The SDK's public surface always uses {@link MinorUnits} (the scale-4 integer),
+ * matching `docs/realtime-sdk-contract.ts`. Convert at the REST boundary with
+ * {@link decimalToMinor} (read) / {@link minorToAmount} (write), and display with
+ * {@link formatMoney}. Never do money math beyond display.
+ */
+/** Integer minor units at scale 4 (i.e. major × 10_000). `125000` ⇒ `12.5000`. */
+type MinorUnits = number;
+/** Decimal places the runtime stores. Do not change without the runtime changing. */
+declare const MONEY_SCALE = 4;
+/**
+ * Convert a runtime decimal string (or number) to scale-4 minor units.
+ * `"12.5000"` ⇒ `125000`. Throws on non-numeric input.
+ */
+declare function decimalToMinor(value: string | number): MinorUnits;
+/**
+ * Parse a runtime **minor-unit integer string** (`"1000000"` ⇒ `1000000`) — the
+ * encoding the player history surfaces (`/player/cashier/*`, `/player/bets`,
+ * `/player/game-sessions`, `/player/limits`) use, unlike the 4-dp decimal
+ * strings elsewhere (use {@link decimalToMinor} for those).
+ *
+ * Strict by design: only canonical digit strings (`/^-?\d+$/`) within the safe
+ * integer range are accepted. A 4-dp decimal that happens to be integral
+ * (`"50.0000"`) is a WRONG-SURFACE value — accepting it would misread €50.00 as
+ * 50 minor units (a 10 000× error) — and an over-`MAX_SAFE_INTEGER` string would
+ * silently lose minor units. Both throw so contract drift is loud.
+ */
+declare function minorStringToMinor(value: string): MinorUnits;
+/**
+ * Convert scale-4 minor units to the plain major-unit **number** the runtime's
+ * write schemas expect (`amount: z.number()`). `125000` ⇒ `12.5`. Safe for the
+ * 4-dp range: a scale-4 integer divided by 10⁴ round-trips exactly through JSON.
+ */
+declare function minorToAmount(minor: MinorUnits): number;
+/**
+ * Convert scale-4 minor units back to a canonical 4-dp decimal string
+ * (`125000` ⇒ `"12.5000"`) — the format REST **responses** use. Kept public for
+ * symmetry/display; note the runtime's write paths take numbers, not strings
+ * (use {@link minorToAmount} there).
+ */
+declare function minorToDecimal(minor: MinorUnits): string;
+/**
+ * Format minor units for display in the currency's natural precision.
+ * `formatMoney(125000, "EUR")` ⇒ `"€12.50"` (en locale). Uses `Intl.NumberFormat`;
+ * pass `locale` to localize, or `{ minimumFractionDigits }` to show all 4 dp.
+ */
+declare function formatMoney(minor: MinorUnits, currency: string, options?: {
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}): string;
+
+/**
+ * Transport types — the player-facing HTTP contract, hand-authored from the
+ * runtime route files + Zod schemas (the "manual fallback" of contract sync;
+ * see `docs/SDK_BIBLE.md` → Versioning for the swagger follow-up).
+ *
+ * Money fields that the runtime serializes as 4-dp decimal strings are typed as
+ * `MinorUnits` here because the SDK converts them at the transport boundary
+ * (`src/modules/*`), so app code only ever sees scale-4 integers.
+ *
+ * Targets runtime API: see `RUNTIME_API_VERSION` in `src/index.ts`.
+ */
+
+type PlayerStatus = "active" | "suspended" | "closed" | "pending_verification" | "self_excluded";
+/** Shared pagination block on the new player-facing history endpoints. */
+interface PageInfo {
+    limit: number;
+    offset: number;
+    /** Total rows for the player, across all pages. */
+    total: number;
+    /** True when `offset + returned < total`. */
+    hasMore: boolean;
+}
+interface Player {
+    id: string;
+    tenantId: string;
+    externalId: string | null;
+    username: string | null;
+    email: string | null;
+    phone: string | null;
+    status: PlayerStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+interface PlayerProfile {
+    firstName?: string | null;
+    lastName?: string | null;
+    birthDate?: string | null;
+    gender?: string | null;
+    country?: string | null;
+    city?: string | null;
+    address?: string | null;
+    language?: string | null;
+    currency?: string | null;
+    timezone?: string | null;
+    avatarUrl?: string | null;
+}
+/** Three wallet buckets, all in scale-4 minor units. */
+interface WalletBuckets {
+    cash: MinorUnits;
+    bonus: MinorUnits;
+    locked: MinorUnits;
+}
+interface Paginated<T> {
+    rows: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Attribution hints carried from the affiliate click chain into signup. Optional
+ * and best-effort — signup never fails on them — but they can only be captured
+ * here: a click chain not carried at signup is unrecoverable. `clickId` is the
+ * value returned by {@link TrackClickResult} (persist it client-side after
+ * `affiliate.trackClick` and pass it through here).
+ */
+interface SignupAttribution {
+    /** The `clickId` from `affiliate.trackClick` — the click → registration join key. */
+    clickId?: string;
+    /** Affiliate public tracking code, when the `clickId` was not captured. */
+    affiliateCode?: string;
+    deviceFingerprint?: string;
+}
+interface SignupInput {
+    email: string;
+    password: string;
+    username?: string;
+    profile?: {
+        firstName?: string;
+        lastName?: string;
+        country?: string;
+        currency?: string;
+        language?: string;
+    };
+    /** Affiliate attribution captured at click time; see {@link SignupAttribution}. */
+    attribution?: SignupAttribution;
+}
+interface LoginInput {
+    email: string;
+    password: string;
+}
+/** Response of signup/login/refresh/social-callback. Cookies are set by the runtime. */
+interface AuthSession {
+    player: Player;
+    csrfToken: string;
+}
+interface MeResponse {
+    player: Player;
+    profile: PlayerProfile | null;
+}
+type SocialProvider = "google" | "discord" | "apple" | "telegram" | "facebook" | "twitter" | "github" | "custom";
+interface SocialAccount {
+    id: string;
+    tenantId: string;
+    playerId: string;
+    provider: string;
+    providerUserId: string;
+    providerEmail?: string | null;
+    providerUsername?: string | null;
+    providerAvatarUrl?: string | null;
+    /** Raw provider profile payload as stored by the runtime. */
+    providerData?: unknown;
+    linkedAt: string;
+}
+/**
+ * Player-facing view of a login session — the "your devices" surface. Omits the
+ * refresh-token hash and rotation linkage (server-internal). Dates are ISO strings
+ * on the wire.
+ */
+interface SafeSession {
+    id: string;
+    /** True for the session this request is authenticated with ("this device"). */
+    current: boolean;
+    /** Not revoked and not expired. */
+    active: boolean;
+    device: {
+        type: string | null;
+        os: string | null;
+        browser: string | null;
+        model: string | null;
+        /** Human label, e.g. "Chrome on macOS". */
+        label: string;
+    };
+    location: {
+        city: string | null;
+        region: string | null;
+        country: string | null;
+    };
+    ip: string | null;
+    createdAt: string;
+    /** Refreshed on token rotation (throttled server-side); null for old sessions. */
+    lastSeenAt: string | null;
+    expiresAt: string;
+    revokedAt: string | null;
+}
+interface SessionHistoryQuery {
+    /** Page size, 1–100. Runtime default 50. */
+    limit?: number;
+    /** Runtime default 0. */
+    offset?: number;
+}
+/** One page of session history (`GET /auth/player/sessions/history`). */
+interface SessionHistoryPage {
+    sessions: SafeSession[];
+    pagination: {
+        limit: number;
+        offset: number;
+        /** Total sessions for the player, across all pages. */
+        total: number;
+        /** True when `offset + returned < total`. */
+        hasMore: boolean;
+    };
+}
+/**
+ * One login attempt (`GET /auth/player/login-history`). `failReason` values
+ * observed from the runtime: `invalid_credentials`, `account_inactive`,
+ * `account_locked`; null on success.
+ */
+interface LoginAttempt {
+    id: string;
+    at: string;
+    ip: string | null;
+    device: {
+        type: string | null;
+        os: string | null;
+        browser: string | null;
+        label: string;
+    };
+    location: {
+        country: string | null;
+        city: string | null;
+    };
+    method: "password" | "social" | "refresh";
+    success: boolean;
+    failReason: string | null;
+}
+interface LoginHistoryPage {
+    attempts: LoginAttempt[];
+    pagination: PageInfo;
+}
+/**
+ * `200` of email/phone verification request. `expiresIn` is the credential TTL
+ * in seconds; `resendIn` is the cooldown before another request is accepted
+ * (a premature retry returns 429 `RATE_LIMITED` with `details.resendIn`).
+ */
+interface VerificationRequestResult {
+    success: true;
+    expiresIn: number;
+    resendIn: number;
+}
+/**
+ * The full profile row as `GET /player/profile` serializes it (unlike the
+ * partial {@link PlayerProfile} on `/auth/player/me`, every field is present,
+ * nullable). `birthDate` is a `YYYY-MM-DD` string.
+ */
+interface PlayerProfileRecord {
+    playerId: string;
+    tenantId: string;
+    firstName: string | null;
+    lastName: string | null;
+    birthDate: string | null;
+    gender: string | null;
+    country: string | null;
+    city: string | null;
+    address: string | null;
+    language: string | null;
+    currency: string | null;
+    timezone: string | null;
+    avatarUrl: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ProfileResponse {
+    /** Null until the player has a profile row. */
+    profile: PlayerProfileRecord | null;
+    /**
+     * Identity fields locked after KYC approval (`firstName`/`lastName`/
+     * `birthDate`/`country`); patching them fails 409 `PROFILE_FIELD_LOCKED`.
+     */
+    lockedFields: string[];
+}
+/**
+ * Body of `PATCH /player/profile`. All fields optional, at least one required;
+ * `null` clears a field. Identity fields are rejected after KYC approval.
+ */
+interface UpdateProfileInput {
+    firstName?: string | null;
+    lastName?: string | null;
+    /** `YYYY-MM-DD`. */
+    birthDate?: string | null;
+    gender?: string | null;
+    /** ISO 3166-1 alpha-2. */
+    country?: string | null;
+    city?: string | null;
+    address?: string | null;
+    language?: string | null;
+    timezone?: string | null;
+    avatarUrl?: string | null;
+}
+interface UpdateProfileResult {
+    profile: PlayerProfileRecord;
+    /** Keys whose value actually changed (may be empty for a no-op patch). */
+    changedFields: string[];
+}
+type OddsFormat = "decimal" | "fractional" | "american";
+interface PlayerPreferences {
+    language: string | null;
+    timezone: string | null;
+    displayCurrency: string | null;
+    oddsFormat: string | null;
+    marketing: {
+        email: boolean;
+        sms: boolean;
+        push: boolean;
+    };
+    /** Reality-check interval in minutes (5–240); null = disabled. */
+    realityCheckMinutes: number | null;
+}
+/** Body of `PUT /player/preferences` — all optional, at least one required. */
+interface SetPreferencesInput {
+    language?: string;
+    timezone?: string;
+    /** ISO 4217. */
+    displayCurrency?: string;
+    oddsFormat?: OddsFormat;
+    marketing?: {
+        email?: boolean;
+        sms?: boolean;
+        push?: boolean;
+    };
+    /** 5–240 minutes, or null to disable the reality check. */
+    realityCheckMinutes?: number | null;
+}
+/** One append-only consent-trail entry. Keys today: `marketing.{email,sms,push}`. */
+interface ConsentEntry {
+    consentKey: string;
+    granted: boolean;
+    at: string;
+    source: string;
+}
+interface ConsentsPage {
+    consents: ConsentEntry[];
+    pagination: PageInfo;
+}
+/**
+ * GDPR export request state. `POST /player/account/export` answers `202` with
+ * `status: "pending"`; `GET /player/account/export` returns the latest request,
+ * or the bare `{ status: "none" }` when none was ever requested. The download
+ * link is delivered out-of-band, not through these endpoints.
+ */
+type DataExportStatus = {
+    status: "none";
+} | {
+    id: string;
+    status: "pending" | "processing" | "completed" | "failed";
+    requestedAt: string;
+    finishedAt: string | null;
+    expiresAt: string | null;
+};
+type LimitKind = "deposit" | "loss" | "wager" | "session_time";
+/** UTC windows; `week` starts ISO Monday 00:00 UTC. */
+type LimitPeriod = "day" | "week" | "month";
+/**
+ * One active limit (`GET /player/limits`). `value` is scale-4 minor units for
+ * the money kinds (`deposit`/`loss`/`wager`) and **whole minutes** for
+ * `session_time`. Ratchet semantics: a new limit or a decrease applies
+ * immediately (`pending: null`); an increase or removal is stored in `pending`
+ * and applied at `pending.activeAt` (24h cooldown).
+ */
+interface PlayerLimit {
+    kind: LimitKind;
+    period: LimitPeriod;
+    value: MinorUnits;
+    currency: string | null;
+    activeFrom: string;
+    pending: {
+        /** The value that will apply (null for a pending removal). */
+        value: MinorUnits | null;
+        removal: boolean;
+        activeAt: string;
+    } | null;
+}
+/**
+ * One entry of `PUT /player/limits`. `value` in scale-4 minor units (minutes
+ * for `session_time`); `null` requests removal of the existing limit.
+ */
+interface SetLimitInput {
+    kind: LimitKind;
+    period: LimitPeriod;
+    value: MinorUnits | null;
+    /** ISO 4217, for money kinds. */
+    currency?: string;
+}
+/** Cool-off blocks gameplay + deposits (login/withdrawal stay); extend-only. */
+type CoolOffPeriod = "24h" | "48h" | "7d" | "30d";
+/** Self-exclusion is irreversible player-side; `permanent` has no end date. */
+type SelfExclusionPeriod = "6m" | "1y" | "5y" | "permanent";
+type KycTrigger = "manual" | "signup" | "deposit_total_threshold" | "withdrawal_amount_threshold" | "withdrawal_total_threshold" | "risk_flag";
+type KycRequestStatus = "draft" | "submitted" | "in_review" | "approved" | "rejected" | "needs_more";
+type KycDocumentStatus = "uploaded" | "in_review" | "approved" | "rejected";
+type PlayerKycStatus = "none" | "pending" | "approved" | "rejected" | "expired";
+/** `GET /player/kyc/status`. */
+interface KycStatusResponse {
+    /** Verification level 0–3. */
+    level: number;
+    status: PlayerKycStatus;
+    approvedAt: string | null;
+    emailVerified: boolean;
+    phoneVerified: boolean;
+    gates: {
+        withdrawal: {
+            requiredLevel: number;
+            met: boolean;
+        };
+    };
+}
+/** Latest upload for a checklist item (metadata only — players cannot download). */
+interface KycItemDocument {
+    id: string;
+    status: KycDocumentStatus;
+    fileName: string;
+    uploadedAt: string;
+    rejectionReason: string | null;
+}
+interface KycChecklistItem {
+    /** e.g. `passport`, `id_front`, `proof_of_address`, `selfie`. */
+    documentTypeKey: string;
+    title: string;
+    required: boolean;
+    sort: number;
+    source: "set" | "needs_more" | "plugin";
+    document: KycItemDocument | null;
+}
+/** One open KYC request (`GET /player/kyc/requirements`). */
+interface KycRequest {
+    id: string;
+    trigger: KycTrigger;
+    status: KycRequestStatus;
+    targetLevel: number | null;
+    createdAt: string;
+    items: KycChecklistItem[];
+}
+interface KycHistoryEntry {
+    id: string;
+    trigger: KycTrigger;
+    status: KycRequestStatus;
+    targetLevel: number | null;
+    decisionReasonCode: string | null;
+    createdAt: string;
+    reviewedAt: string | null;
+}
+interface KycHistoryPage {
+    requests: KycHistoryEntry[];
+    pagination: PageInfo;
+}
+/**
+ * A KYC document upload. Accepted content: JPEG/PNG/PDF, sniffed server-side
+ * from magic bytes (the declared content-type is ignored); 25 MB transport cap,
+ * per-type cap (default 10 MB) enforced at 422 `KYC_DOCUMENT_INVALID`.
+ */
+interface KycUploadInput {
+    /** Attach to an open request (`draft`/`needs_more`); omit for a proactive upload. */
+    requestId?: string;
+    documentTypeKey: string;
+    /** The file content. In Node pass a `Blob`/`File` (both global on Node ≥20). */
+    file: Blob;
+    /** Filename sent in the multipart part; defaults to `File.name` or `document`. */
+    fileName?: string;
+    /** `YYYY-MM-DD`; required for document types with `requiresExpiryDate` (e.g. passport). */
+    expiryDate?: string;
+}
+/** `201` of a KYC document upload. */
+interface KycUploadResult {
+    documentId: string;
+    status: "uploaded";
+}
+interface DepositInput {
+    /** Defaults to the authenticated player. */
+    playerId?: string;
+    /** Amount in scale-4 minor units. */
+    amount: MinorUnits;
+    /** Defaults to the client/profile currency. */
+    currency?: string;
+    providerKey?: string;
+    methodKey?: string;
+    instrumentId?: string;
+    /** FX snapshot currency (ISO 4217) for base-currency analytics. */
+    baseCurrency?: string;
+    returnUrl?: string;
+    /** Auto-generated if omitted. */
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+}
+type DepositTxStatus = "initiated" | "pending_provider" | "authorized" | "captured" | "completed" | "failed" | "refunded" | "chargeback";
+interface DepositResult {
+    depositId: string;
+    status: DepositTxStatus;
+    providerKey?: string;
+    sourceTxId?: string;
+    /** PSP redirect/3DS/QR instruction; provider-specific. Render or follow as told. */
+    nextAction?: unknown;
+    walletTransactionId?: string;
+    balances?: WalletBuckets;
+    idempotent: boolean;
+    /** Present when a gate plugin requires a step-up (e.g. KYC) before the deposit proceeds. */
+    challenge?: {
+        challenge: string;
+        reason?: string;
+    };
+}
+interface WithdrawalInput {
+    playerId?: string;
+    amount: MinorUnits;
+    currency?: string;
+    providerKey?: string;
+    methodKey?: string;
+    instrumentId?: string;
+    /** FX snapshot currency (ISO 4217) for base-currency analytics. */
+    baseCurrency?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+}
+type WithdrawalTxStatus = "requested" | "pending_review" | "approved" | "processing" | "paid" | "rejected" | "failed" | "cancelled";
+interface WithdrawalResult {
+    withdrawalId: string;
+    status: WithdrawalTxStatus;
+    reviewVerdict?: string;
+    providerKey?: string;
+    sourceTxId?: string;
+    balances?: WalletBuckets;
+    idempotent: boolean;
+}
+/** Shared filter block on the cashier/gaming history endpoints. */
+interface HistoryRangeQuery {
+    /** ISO date(-time) or `Date`. */
+    from?: string | Date;
+    to?: string | Date;
+    /** 1–100, runtime default 50. */
+    limit?: number;
+    offset?: number;
+}
+interface DepositHistoryQuery extends HistoryRangeQuery {
+    status?: DepositTxStatus;
+    providerKey?: string;
+}
+/** One deposit (`GET /player/cashier/deposits`), amounts in minor units. */
+interface DepositSummary {
+    id: string;
+    amount: MinorUnits;
+    currency: string;
+    status: DepositTxStatus;
+    providerKey: string;
+    methodKey: string | null;
+    isFirstDeposit: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `GET /player/cashier/deposits/:id`. */
+interface DepositDetail extends DepositSummary {
+    walletTransactionId: string | null;
+    failureReason: string | null;
+    /** Only non-null while the deposit is `initiated`/`pending_provider`. */
+    nextAction: unknown | null;
+}
+interface DepositHistoryPage {
+    deposits: DepositSummary[];
+    pagination: PageInfo;
+}
+interface WithdrawalHistoryQuery extends HistoryRangeQuery {
+    status?: WithdrawalTxStatus;
+}
+/** One withdrawal (`GET /player/cashier/withdrawals`), amounts in minor units. */
+interface WithdrawalSummary {
+    id: string;
+    amount: MinorUnits;
+    currency: string;
+    status: WithdrawalTxStatus;
+    providerKey: string | null;
+    methodKey: string | null;
+    reviewVerdict: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `GET /player/cashier/withdrawals/:id`. */
+interface WithdrawalDetail extends WithdrawalSummary {
+    failureReason: string | null;
+    /** Wallet transaction ids of the reserve/settle/release legs. */
+    walletTransactionIds: {
+        reserve: string | null;
+        settle: string | null;
+        release: string | null;
+    };
+}
+interface WithdrawalHistoryPage {
+    withdrawals: WithdrawalSummary[];
+    pagination: PageInfo;
+}
+/**
+ * A payment method available to the player (`GET /player/cashier/methods`),
+ * sorted by `sort` ascending. `limits` are converted to minor units.
+ */
+interface PaymentMethod {
+    methodKey: string;
+    providerKey: string;
+    title: string;
+    kind: "card" | "bank" | "ewallet" | "crypto" | "voucher";
+    direction: "deposit" | "withdrawal" | "both";
+    limits: {
+        min: MinorUnits;
+        max: MinorUnits;
+        currency: string;
+    };
+    /** Present when the method is gated behind a KYC level. */
+    requiresKycLevel?: number;
+    /** Extra inputs the method needs (e.g. IBAN); render as a form. */
+    fields?: Array<{
+        key: string;
+        label: string;
+        type: "text" | "number" | "select";
+        required?: boolean;
+        options?: string[];
+    }>;
+    sort: number;
+}
+interface BalanceResponse {
+    playerId: string;
+    currency: string;
+    cash: MinorUnits;
+    bonus: MinorUnits;
+    locked: MinorUnits;
+    total: MinorUnits;
+    /** `closed` is terminal; `frozen` is reversible. See the runtime wallet state machine. */
+    status: "active" | "frozen" | "closed";
+    walletId: string | null;
+}
+type TransactionType = "credit" | "debit" | "deposit" | "withdrawal" | "bet" | "win" | "bonus" | "rollback" | "transfer" | "adjustment";
+type TransactionStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" | "reversed";
+interface WalletTransaction {
+    id: string;
+    walletId: string;
+    playerId: string;
+    externalTransactionId: string | null;
+    type: TransactionType;
+    amount: MinorUnits;
+    currency: string;
+    source: string;
+    gameId: string | null;
+    /** The replay-guard key the write was made with. */
+    idempotencyKey: string;
+    metadata: Record<string, unknown> | null;
+    status: TransactionStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TransactionsQuery {
+    playerId?: string;
+    walletId?: string;
+    type?: TransactionType;
+    status?: TransactionStatus;
+    currency?: string;
+    limit?: number;
+    offset?: number;
+}
+/** The three wallet buckets a ledger leg can move. */
+type WalletBucketName = "cash" | "bonus" | "locked";
+/**
+ * One append-only ledger leg (`GET /wallet/ledger`) — a single bucket movement
+ * with its before/after balance snapshot. Amounts in scale-4 minor units.
+ */
+interface LedgerEntry {
+    id: string;
+    walletId: string;
+    transactionId: string;
+    playerId: string;
+    walletType: WalletBucketName;
+    direction: "credit" | "debit";
+    amount: MinorUnits;
+    currency: string;
+    balanceBefore: MinorUnits;
+    balanceAfter: MinorUnits;
+    createdAt: string;
+}
+interface LedgerQuery {
+    playerId?: string;
+    walletId?: string;
+    walletType?: WalletBucketName;
+    transactionId?: string;
+    limit?: number;
+    offset?: number;
+}
+interface GameFeatures {
+    hasDemo?: boolean;
+    isVirtual?: boolean;
+    bonusBuy?: boolean;
+    megaways?: boolean;
+    [key: string]: unknown;
+}
+interface Game {
+    id: string;
+    slug: string | null;
+    title: string | null;
+    name?: unknown;
+    providerId: string;
+    launchCode: string | null;
+    imageUrl: string | null;
+    rtp: string | null;
+    minBet: string | null;
+    maxBet: string | null;
+    featured: boolean;
+    features: GameFeatures;
+}
+interface GamePage {
+    games: Game[];
+    page: {
+        limit: number;
+        offset: number;
+        count: number;
+    };
+}
+interface CategoryNode {
+    id: string;
+    slug: string;
+    title: string | null;
+    kind: string;
+    sort: number;
+    children: CategoryNode[];
+}
+interface Provider {
+    id: string;
+    externalId: string;
+    name: string;
+    alias: string | null;
+    logoUrl: string | null;
+    logoPath: string | null;
+    weight: number;
+    parentProviderId: string | null;
+}
+interface GeoQuery {
+    country?: string;
+    /** Sub-national code, e.g. `"CA-QC"`. */
+    subdivision?: string;
+    currency?: string;
+    locale?: string;
+    device?: string;
+}
+interface LobbyQuery extends GeoQuery {
+    limit?: number;
+    offset?: number;
+}
+interface SearchQuery extends LobbyQuery {
+    q?: string;
+    /** Provider id, name, or alias; expands to its sub-providers server-side. */
+    provider?: string;
+    /** Category id or slug (e.g. `"slots"`); includes the category subtree. */
+    category?: string;
+    hasDemo?: boolean;
+    isVirtual?: boolean;
+    bonusBuy?: boolean;
+    megaways?: boolean;
+}
+/**
+ * @deprecated Input for the removed SlotServ aggregation route (`POST
+ * /plugins/slotserv/launch`); `games.launch()` is a stub now. The live launch
+ * path — `games.providerSession()` — takes `playerId`/`currency` options only.
+ */
+interface LaunchInput {
+    playerId?: string;
+    currency?: string;
+    device?: string;
+    locale?: string;
+    mode?: "real" | "demo";
+    country?: string;
+}
+/** Response of `POST /providers/:provider/session`. */
+interface LaunchResult {
+    provider: string;
+    /** The game session id. */
+    sessionId: string;
+    /** Fully-formed URL to render in the game iframe. */
+    launchUrl: string;
+}
+type BetStatus = "placed" | "settled" | "rolled_back";
+interface BetsQuery extends HistoryRangeQuery {
+    gameId?: string;
+    providerKey?: string;
+    status?: BetStatus;
+}
+/** One bet (`GET /player/bets`), amounts in minor units. */
+interface Bet {
+    betId: string;
+    roundId: string;
+    gameId: string | null;
+    gameTitle: string | null;
+    providerKey: string;
+    betAmount: MinorUnits;
+    /** Null until settled. */
+    winAmount: MinorUnits | null;
+    currency: string;
+    status: BetStatus;
+    placedAt: string;
+    settledAt: string | null;
+}
+/** `GET /player/bets/:betId` — the bet plus its round-linked wallet transactions. */
+interface BetDetail extends Bet {
+    walletTransactions: Array<{
+        id: string;
+        type: string;
+    }>;
+}
+interface BetsPage {
+    bets: Bet[];
+    pagination: PageInfo;
+}
+/** One game session (`GET /player/game-sessions`), totals in minor units. */
+interface GameSession {
+    id: string;
+    providerKey: string;
+    gameId: string | null;
+    currency: string | null;
+    status: "active" | "ended";
+    betCount: number;
+    betTotal: MinorUnits;
+    winTotal: MinorUnits;
+    startedAt: string;
+    lastActivityAt: string | null;
+    endedAt: string | null;
+}
+interface GameSessionsPage {
+    sessions: GameSession[];
+    pagination: PageInfo;
+}
+/** Up to five free-form sub-tracking ids an affiliate appends to their link. */
+interface AffiliateSubIds {
+    subId1?: string;
+    subId2?: string;
+    subId3?: string;
+    subId4?: string;
+    subId5?: string;
+}
+/** Standard UTM parameters captured from the landing URL. */
+interface UtmParams {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+}
+/**
+ * Body of `POST /affiliate/track/click`. The runtime validates `.strict()` —
+ * unknown keys are rejected — and captures `ip`/`user-agent` server-side.
+ * `referrer` falls back to the `Referer` header when omitted.
+ */
+interface TrackClickInput {
+    /** The affiliate's public tracking code from the landing link (required). */
+    affiliateCode: string;
+    campaignId?: string;
+    creativeId?: string;
+    subIds?: AffiliateSubIds;
+    /** Google Ads click id. */
+    gclid?: string;
+    /** Meta click id. */
+    fbclid?: string;
+    /** TikTok click id. */
+    ttclid?: string;
+    /** Microsoft Ads click id. */
+    msclkid?: string;
+    utm?: UtmParams;
+    landingPage?: string;
+    referrer?: string;
+    deviceFingerprint?: string;
+}
+/**
+ * `201` response of the click capture. Store `clickId` client-side
+ * (cookie/localStorage) and pass it through signup — it is the
+ * click → registration join key.
+ */
+interface TrackClickResult {
+    clickId: string;
+}
+
+/**
+ * `sdk.affiliate` — affiliate click tracking.
+ *
+ * Maps to the runtime's one public affiliate endpoint, `POST /affiliate/track/click`.
+ * Call it on the landing page; anything not captured at click time (gclid/fbclid/…)
+ * is unrecoverable. The endpoint is rate-limited per IP (`RateLimitError` on 429).
+ */
+
+declare class AffiliateModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Record an affiliate click. Returns the `clickId` join key — persist it
+     * (cookie/localStorage) and carry it into signup so the registration can be
+     * attributed to the click.
+     */
+    trackClick(input: TrackClickInput): Promise<TrackClickResult>;
+}
+
+/**
+ * Session state held client-side.
+ *
+ * Several runtime endpoints need the player's id and/or currency that the SDK can
+ * supply automatically once the player has authenticated:
+ *
+ * - cashier `deposits`/`withdrawals` take `playerId` in the body,
+ * - `GET /wallet/balance` and `/wallet/transactions` take `playerId` + `currency`,
+ * - provider game sessions (`providerSession`) take `playerId` + `currency`.
+ *
+ * Auth responses (`signup`/`login`/`me`) populate this cache so callers don't have
+ * to thread `playerId` through every call. Every method still accepts an explicit
+ * override.
+ */
+
+interface SessionSnapshot {
+    player: Player | null;
+    profile: PlayerProfile | null;
+    /** Default currency: profile currency, else the client's configured default. */
+    currency: string;
+}
+declare class Session {
+    private player;
+    private profile;
+    private readonly fallbackCurrency;
+    constructor(fallbackCurrency: string);
+    setPlayer(player: Player | null, profile?: PlayerProfile | null): void;
+    clear(): void;
+    get playerId(): string | undefined;
+    /** Resolve a playerId, preferring an explicit override; throws if neither exists. */
+    requirePlayerId(override?: string): string;
+    /** Resolve a currency: override → profile → configured default. */
+    resolveCurrency(override?: string): string;
+    snapshot(): SessionSnapshot;
+}
+
+/**
+ * `sdk.auth` — signup, login, logout, refresh, me, social OAuth, and sessions
+ * ("your devices").
+ *
+ * Maps to the runtime's `/auth/player/*` routes. Auth is cookie-based: the runtime
+ * sets `cwe_access_token` / `cwe_refresh_token` (HttpOnly) and `cwe_csrf` (readable);
+ * the SDK's HTTP layer carries the session and CSRF automatically. After a
+ * successful auth call the {@link Session} cache is populated so wallet/cashier/launch
+ * calls can auto-fill `playerId` + `currency`.
+ */
+
+interface SocialStartOptions {
+    /**
+     * Where the runtime should send the player back after the provider flow.
+     * Use `https:` URLs only — a non-https `redirectUri` (or worse, a scheme like
+     * `javascript:`) must never reach a browser navigation. The runtime validates
+     * it against the tenant's allowlist; keep your allowlist https-only too.
+     */
+    redirectUri?: string;
+}
+declare class AuthModule {
+    private readonly http;
+    private readonly session;
+    private readonly baseUrl;
+    constructor(http: HttpClient, session: Session, baseUrl: string);
+    /** Create an account and start a session. */
+    signup(input: SignupInput): Promise<AuthSession>;
+    /** Log in with email + password and start a session. */
+    login(input: LoginInput): Promise<AuthSession>;
+    /** End the session and clear the cached player. */
+    logout(): Promise<void>;
+    /**
+     * Rotate the session using the refresh cookie. Called automatically by the HTTP
+     * layer on a 401; you rarely call it directly.
+     *
+     * The request is marked `_noRefresh`: a 401 here (fully logged out) must throw
+     * immediately instead of re-entering the 401 → refresh path it is part of.
+     */
+    refresh(): Promise<AuthSession>;
+    /** Current player + profile. Refreshes the session cache (incl. default currency). */
+    me(): Promise<MeResponse>;
+    readonly social: {
+        /**
+         * Build the URL that begins a social login. Send the browser here (full
+         * navigation, not fetch) so the runtime can redirect to the provider.
+         */
+        startUrl: (provider: SocialProvider, options?: SocialStartOptions) => string;
+        /**
+         * Complete the OAuth callback (provider → your app) by exchanging `code`+`state`.
+         * Use this if your app handles the callback route itself; otherwise the runtime
+         * handles `/auth/player/social/:provider/callback` directly.
+         */
+        callback: (provider: SocialProvider, params: {
+            code?: string;
+            state?: string;
+            hash?: string;
+        }) => Promise<AuthSession>;
+        /** Link a social account to the logged-in player. */
+        link: (provider: SocialProvider, code: string) => Promise<{
+            account: SocialAccount;
+        }>;
+        /** Unlink a previously-linked social account. */
+        unlink: (provider: SocialProvider, socialAccountId: string) => Promise<{
+            success: true;
+        }>;
+    };
+    /**
+     * Session management — the "your devices" surface. The runtime scopes every call
+     * to the authenticated player (the id comes from the verified principal, never a
+     * path), so a player can only see and revoke their own sessions.
+     */
+    readonly sessions: {
+        /** Active sessions — the player's currently signed-in devices. */
+        list: () => Promise<SafeSession[]>;
+        /**
+         * Full session history — active plus revoked/expired, newest first. Paginated:
+         * `limit` 1–100 (default 50), `offset` ≥ 0; `pagination.hasMore` says whether
+         * another page exists.
+         */
+        history: (query?: SessionHistoryQuery) => Promise<SessionHistoryPage>;
+        /** Disconnect (revoke) one of the player's own sessions. */
+        revoke: (sessionId: string) => Promise<{
+            success: true;
+        }>;
+        /**
+         * Revoke every session. By default the current one survives ("sign out
+         * everywhere else"); pass `{ exceptCurrent: false }` to revoke this device
+         * too (the runtime then also clears the auth cookies).
+         */
+        revokeAll: (options?: {
+            exceptCurrent?: boolean;
+        }) => Promise<{
+            revoked: number;
+        }>;
+    };
+    /**
+     * Login history (successful and failed attempts, newest first). Paginated:
+     * `limit` 1–100 (default 50), `offset` ≥ 0.
+     */
+    loginHistory(query?: SessionHistoryQuery): Promise<LoginHistoryPage>;
+    /** Password management. The reset flow is anonymous; `change` needs a session. */
+    readonly password: {
+        /**
+         * Change the password (requires the current one). The runtime revokes every
+         * OTHER session; this one survives. Rate-limited 10/h per player.
+         */
+        change: (input: {
+            currentPassword: string;
+            newPassword: string;
+        }) => Promise<{
+            success: true;
+        }>;
+        /**
+         * Request a password-reset email. Always resolves `{ success: true }`
+         * (anti-enumeration) — even for unknown emails or while rate-limited.
+         */
+        requestReset: (email: string) => Promise<{
+            success: true;
+        }>;
+        /**
+         * Complete a reset with the emailed token. Revokes ALL sessions — the
+         * player must log in again.
+         */
+        confirmReset: (input: {
+            token: string;
+            newPassword: string;
+        }) => Promise<{
+            success: true;
+        }>;
+    };
+    /**
+     * Email/phone verification. `request` sends the token/OTP (429 with
+     * `details.resendIn` inside the cooldown); `confirm` verifies it.
+     */
+    readonly verification: {
+        email: {
+            request: () => Promise<VerificationRequestResult>;
+            /** Confirm with the emailed link `token` XOR the 6-digit `code` (code needs a session). */
+            confirm: (input: {
+                token?: string;
+                code?: string;
+            }) => Promise<{
+                verified: true;
+            }>;
+        };
+        phone: {
+            /** Pass `phone` to verify a NEW number (applied on confirm). */
+            request: (phone?: string) => Promise<VerificationRequestResult>;
+            confirm: (code: string) => Promise<{
+                verified: true;
+            }>;
+        };
+    };
+}
+
+/**
+ * `sdk.cashier` — deposits & withdrawals.
+ *
+ * Maps to `POST /cashier/deposits` and `POST /cashier/withdrawals`. These are money
+ * operations: the HTTP layer auto-generates an idempotency key (body + header), and
+ * the SDK auto-fills `playerId` + `currency` from the session. Amounts are passed in
+ * minor units and converted to the plain major-unit number the runtime's write
+ * schemas require; any `balances` in the response (4-dp decimal strings) are
+ * converted back to minor units.
+ */
+
+declare class CashierModule {
+    private readonly http;
+    private readonly session;
+    constructor(http: HttpClient, session: Session);
+    /**
+     * Initiate a deposit. Follow `result.nextAction` for any PSP redirect/3DS step;
+     * a `result.challenge` means a gate plugin requires a step-up (e.g. KYC) first.
+     */
+    deposit(input: DepositInput): Promise<DepositResult>;
+    /** Request a withdrawal. May land in `pending_review` depending on risk rules. */
+    withdraw(input: WithdrawalInput): Promise<WithdrawalResult>;
+    /**
+     * The payment methods available to the player (`GET /player/cashier/methods`),
+     * sorted for display; `limits` in minor units. Cached 60s server-side.
+     */
+    listMethods(options?: {
+        currency?: string;
+    }): Promise<PaymentMethod[]>;
+    /** Deposit history, newest first, amounts in minor units. */
+    deposits(query?: DepositHistoryQuery): Promise<DepositHistoryPage>;
+    /**
+     * One deposit with its wallet linkage and any pending `nextAction`
+     * (`GET /player/cashier/deposits/:id`). Realtime `wallet.deposit` remains the
+     * push channel; this is the authoritative re-read.
+     */
+    depositStatus(depositId: string): Promise<DepositDetail>;
+    /** Withdrawal history, newest first, amounts in minor units. */
+    withdrawals(query?: WithdrawalHistoryQuery): Promise<WithdrawalHistoryPage>;
+    /** One withdrawal with its reserve/settle/release wallet-transaction legs. */
+    withdrawalStatus(withdrawalId: string): Promise<WithdrawalDetail>;
+    /**
+     * Cancel a withdrawal that hasn't been picked up yet (`requested`/
+     * `pending_review` only — anything later is a `ConflictError` with code
+     * `INVALID_WITHDRAWAL_STATE`). Releases the reserved funds; idempotent
+     * (a replay returns `idempotent: true` without balances).
+     */
+    cancelWithdrawal(withdrawalId: string): Promise<WithdrawalResult>;
+}
+
+/**
+ * `sdk.wallet` — balance buckets, transaction history, and the append-only ledger.
+ *
+ * Maps to `GET /wallet/balance`, `GET /wallet/transactions`, and `GET /wallet/ledger`.
+ * All take the player's id (auto-filled from the session); balance also takes a
+ * currency (defaults to the profile/config currency). All money is converted to
+ * scale-4 minor units here.
+ */
+
+declare class WalletModule {
+    private readonly http;
+    private readonly session;
+    constructor(http: HttpClient, session: Session);
+    /** Current balance across the cash/bonus/locked buckets, in minor units. */
+    getBalance(options?: {
+        playerId?: string;
+        currency?: string;
+    }): Promise<BalanceResponse>;
+    /** Paginated transaction history (newest first), amounts in minor units. */
+    transactions(query?: TransactionsQuery): Promise<Paginated<WalletTransaction>>;
+    /**
+     * Paginated append-only ledger (newest first) — one row per bucket movement,
+     * with before/after balance snapshots, amounts in minor units. Filter by
+     * `transactionId` to see the legs of a single transaction.
+     */
+    ledger(query?: LedgerQuery): Promise<Paginated<LedgerEntry>>;
+    /**
+     * Fetch a single transaction by id.
+     *
+     * @remarks Not available to players yet — the runtime route
+     * `GET /wallet/transactions/:id` requires staff permission. Tracked on the
+     * roadmap; use {@link transactions} to page history in the meantime.
+     */
+    getTransaction(_id: string): Promise<WalletTransaction>;
+}
+
+/**
+ * `sdk.catalog` — lobby, search, categories tree, providers, game detail,
+ * suggested, and trending. All endpoints are public and geo/currency-aware via
+ * query params (`country`, `currency`, `locale`, `device`).
+ *
+ * Maps to the runtime's `/catalog/*` routes.
+ */
+
+declare class CatalogModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** The default lobby, filtered by geo/currency/device. */
+    lobby(query?: LobbyQuery): Promise<GamePage>;
+    /** Search/filter games by text, provider, category, and feature flags. */
+    searchGames(query?: SearchQuery): Promise<GamePage>;
+    /** Trending games over a window (`"all"` by default), most popular first. */
+    trending(query?: GeoQuery & {
+        window?: string;
+        limit?: number;
+    }): Promise<Game[]>;
+    /** The localized category tree (recursive `children`). */
+    categories(options?: {
+        locale?: string;
+    }): Promise<CategoryNode[]>;
+    /** All enabled providers for this brand/region. */
+    providers(query?: GeoQuery): Promise<Provider[]>;
+    /** A single game by internal id or slug. */
+    game(idOrSlug: string, query?: GeoQuery): Promise<Game>;
+    /**
+     * Games suggested alongside the given game. Takes the internal game **id** only
+     * (an unknown id — including a slug — yields an empty list, not a 404).
+     */
+    suggested(gameId: string, query?: GeoQuery & {
+        limit?: number;
+    }): Promise<Game[]>;
+}
+
+/**
+ * `sdk.ext` — plugin actions: player-facing features that tenant-enabled plugins
+ * expose on the casino API.
+ *
+ * ```ts
+ * // Discovery
+ * const catalog = await sdk.ext.catalog();
+ * const cashback = await sdk.ext.plugin("cashback");
+ *
+ * // Generic — works for any enabled plugin, no build-time knowledge:
+ * const summary = await sdk.ext("cashback").call("getSummary");
+ * await sdk.ext("cashback").call("claim", { periodId });
+ *
+ * // Typed — when the plugin's generated client package is installed, the
+ * // ExtRegistry augmentation narrows call() keys/input/result (see types/ext.ts).
+ * ```
+ *
+ * `call()` resolves the action descriptor from the cached catalog
+ * (`GET /api/ext/_catalog`, ETag-revalidated, `Cache-Control: max-age` honored),
+ * routes input per the action's method (GET/DELETE ⇒ query, POST/PUT ⇒ JSON body,
+ * `:name` path params substituted from matching top-level input keys), and
+ * auto-generates an `Idempotency-Key` for idempotent mutations. The key travels
+ * as a header only — plugin bodies validate `.strict()`.
+ *
+ * Dev-mode only: input is best-effort checked against the action's JSON schema
+ * (`console.warn`, never a client-side throw — the server's Zod is
+ * authoritative), and `deprecated` actions warn once per action per client.
+ *
+ * Money note: plugin payloads are opaque to the SDK, so no minor-unit conversion
+ * happens here — consult the plugin's own docs for its money shapes.
+ */
+
+interface ExtCatalogOptions {
+    /** Bypass the cache and refetch unconditionally. */
+    force?: boolean;
+}
+/**
+ * The `sdk.ext` surface: callable for a per-plugin handle, plus catalog
+ * discovery. Fully lazy — nothing is fetched until an action is called or the
+ * catalog is requested, and a broken catalog endpoint never affects non-ext SDK
+ * usage.
+ */
+interface ExtModule {
+    /** Typed handle — `pluginKey` is registered in {@link ExtRegistry} (generated client installed). */
+    <K extends keyof ExtRegistry & string>(pluginKey: K): TypedExtPluginClient<ExtRegistry[K]>;
+    /** Generic handle for any enabled plugin; no build-time knowledge needed. */
+    (pluginKey: string): ExtPluginClient;
+    /**
+     * The tenant's plugin catalog. Cached in-memory per `Cache-Control: max-age`
+     * (default 60s) and revalidated via ETag once stale; `{ force: true }`
+     * refetches unconditionally. Concurrent callers share one in-flight fetch.
+     */
+    catalog(opts?: ExtCatalogOptions): Promise<ExtCatalog>;
+    /**
+     * One plugin's catalog entry, straight from
+     * `GET /api/ext/_catalog/:pluginKey`. Rejects with
+     * {@link PluginNotEnabledError} when the plugin is not enabled (404).
+     */
+    plugin(pluginKey: string): Promise<ExtCatalogPlugin>;
+}
+/**
+ * Runtime guard for generated plugin clients: throws
+ * {@link PluginVersionMismatchError} when the installed plugin's **major**
+ * version differs from the expected range's major. `expectedRange` accepts the
+ * common single-major forms a generator emits: `"1"`, `"1.x"`, `"1.2.3"`,
+ * `"^1.2.3"`, `"~1.2"`, `"=1.0.0"`, `"v1"`.
+ */
+declare function assertPluginVersion(catalogEntry: ExtCatalogPlugin, expectedRange: string): void;
+
+/**
+ * `sdk.games` — launch a game session.
+ *
+ * `providerSession` maps to the generic `POST /providers/:provider/session` and
+ * returns a fully-formed `launchUrl` to render in the game iframe plus a
+ * `sessionId`. Provider adapters are registered per tenant in the runtime
+ * (built-in `"fake"` for dev, or plugin-contributed adapters). The SDK never
+ * sees provider secrets; all money flows server-side through the provider →
+ * wallet (and pushes back over the realtime `wallet.balance` channel).
+ *
+ * `launch` is a stub: the runtime removed its route (`POST
+ * /plugins/slotserv/launch`) together with the baked-in SlotServ plugin
+ * (runtime `16d4e5d`); it throws `NotImplementedError` until an aggregation
+ * plugin ships a launch surface again.
+ */
+
+/**
+ * Assert a game `launchUrl` is safe to render in an iframe: `https:` only
+ * (`http:` tolerated for loopback hosts so local dev runtimes keep working).
+ * `javascript:`, `data:`, and every other scheme are rejected — a compromised or
+ * misconfigured provider must not be able to hand the frontend a script URL.
+ *
+ * The SDK applies this to every launch result; it is exported so app code can
+ * re-validate URLs it stored or received elsewhere. Also render the iframe with
+ * `sandbox="allow-scripts allow-same-origin allow-forms"` (see the games guide).
+ *
+ * @returns the URL, unchanged, for fluent use.
+ * @throws ValidationError (`LAUNCH_URL_INVALID`, status 0) when the URL is unsafe.
+ */
+declare function assertLaunchUrl(url: string): string;
+declare class GamesModule {
+    private readonly http;
+    private readonly session;
+    constructor(http: HttpClient, session: Session);
+    /**
+     * @deprecated The runtime removed the SlotServ aggregation route
+     * (`POST /plugins/slotserv/launch`) along with its baked-in plugins
+     * (runtime `16d4e5d`, 2026-07-10) — this now always throws
+     * {@link NotImplementedError}. Launch through a tenant-registered provider
+     * adapter instead: {@link providerSession}. It returns the same
+     * `{ launchUrl, sessionId }` shape.
+     */
+    launch(gameId: string, _input?: LaunchInput): Promise<LaunchResult>;
+    /**
+     * Open a game session with a specific provider adapter via the generic
+     * `POST /providers/:provider/session` route (provider-agnostic counterpart of
+     * {@link launch}). Currency defaults from the session.
+     */
+    providerSession(provider: string, gameId: string, options?: {
+        playerId?: string;
+        currency?: string;
+    }): Promise<LaunchResult>;
+    /** Bet history (`GET /player/bets`), newest first, amounts in minor units. */
+    bets(query?: BetsQuery): Promise<BetsPage>;
+    /** One bet plus its round-linked wallet transactions (`GET /player/bets/:betId`). */
+    bet(betId: string): Promise<BetDetail>;
+    /** Game-session history with per-session bet/win totals in minor units. */
+    gameSessions(query?: {
+        from?: string | Date;
+        to?: string | Date;
+        limit?: number;
+        offset?: number;
+    }): Promise<GameSessionsPage>;
+}
+
+/**
+ * `sdk.kyc` — the player-side KYC surface (`/player/kyc/*`).
+ *
+ * Flow: {@link status} says where the player stands and whether the withdrawal
+ * gate is met; {@link requirements} lists the open requests with their document
+ * checklists; {@link uploadDocument} sends files (multipart; JPEG/PNG/PDF,
+ * sniffed server-side); {@link submit} hands a completed request to review.
+ * Players can never download their documents — item `document` objects are
+ * metadata only. Live status pushes arrive on the realtime `player` channel
+ * (`kyc_status_changed` / `kyc_documents_requested`).
+ *
+ * If the tenant delegates the KYC flow to a plugin, mutations throw
+ * {@link FlowDelegatedError} — drive the plugin's `/api/ext` routes via
+ * `sdk.ext` instead.
+ */
+
+declare class KycModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Verification level, per-gate requirements, and email/phone verification flags. */
+    status(): Promise<KycStatusResponse>;
+    /** Open KYC requests (draft/submitted/in_review/needs_more) with their checklists. */
+    requirements(): Promise<KycRequest[]>;
+    /** All requests, newest first. `limit` 1–100 (default 50). */
+    history(query?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<KycHistoryPage>;
+    /**
+     * Upload a document. With `requestId` it attaches to that request (which must
+     * be `draft`/`needs_more`); without, it is a proactive re-verification
+     * upload. Rejections are `ValidationError` with code `KYC_DOCUMENT_INVALID`
+     * (format/size/expiry — see `details`).
+     *
+     * Large files on slow uplinks can outlive the client's default request
+     * timeout (30s) — raise or disable it per call via `options.timeoutMs`
+     * (`0` disables).
+     */
+    uploadDocument(input: KycUploadInput, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<KycUploadResult>;
+    /**
+     * Submit a request for review. Every `required` checklist item needs an
+     * uploaded/approved document first — otherwise `ValidationError` with
+     * `details.missing` listing the absent `documentTypeKey`s.
+     */
+    submit(requestId: string): Promise<{
+        status: "submitted";
+    }>;
+}
+
+/**
+ * `sdk.player` — profile, preferences, consents, responsible-gaming limits, and
+ * account lifecycle (close / GDPR export).
+ *
+ * Maps to the runtime's `/player/*` account surface. Responsible-gaming limit
+ * values ride the wire as scale-4 minor-unit integer *strings* (minutes for
+ * `session_time`); the SDK converts them to `MinorUnits` numbers at the
+ * boundary. KYC lives at `sdk.kyc`.
+ */
+
+declare class PlayerModule {
+    private readonly http;
+    private readonly auth;
+    constructor(http: HttpClient, auth: AuthModule);
+    /** The logged-in player's identity + profile (via `/auth/player/me`). */
+    getProfile(): Promise<MeResponse>;
+    /**
+     * The full profile row plus which identity fields are KYC-locked
+     * (`GET /player/profile`). `profile` is null until one exists.
+     */
+    profile(): Promise<ProfileResponse>;
+    /**
+     * Patch the profile (`PATCH /player/profile`). At least one field; `null`
+     * clears. Identity fields (`firstName`/`lastName`/`birthDate`/`country`)
+     * throw `ConflictError` (`PROFILE_FIELD_LOCKED`) after KYC approval.
+     */
+    updateProfile(patch: UpdateProfileInput): Promise<UpdateProfileResult>;
+    /** Preferences (locale, display currency, marketing consents, reality check). */
+    getPreferences(): Promise<PlayerPreferences>;
+    /**
+     * Update preferences (`PUT /player/preferences`, partial — at least one
+     * field). Marketing changes are recorded on the consent trail; set
+     * `realityCheckMinutes: null` to disable the reality check.
+     */
+    setPreferences(patch: SetPreferencesInput): Promise<PlayerPreferences>;
+    /** The append-only marketing-consent trail, newest first. */
+    consents(query?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ConsentsPage>;
+    /**
+     * Active responsible-gaming limits, values in minor units (minutes for
+     * `session_time`). `pending` carries a ratcheted increase/removal and when it
+     * applies.
+     */
+    getLimits(): Promise<PlayerLimit[]>;
+    /**
+     * Set/remove limits (`PUT /player/limits`). `value` in minor units (minutes
+     * for `session_time`); `null` removes. New limits and decreases apply
+     * immediately; increases/removals apply after the 24h ratchet cooldown
+     * (returned in `pending`).
+     */
+    setLimits(limits: SetLimitInput[]): Promise<PlayerLimit[]>;
+    /** Responsible-gaming actions beyond limits. */
+    readonly rg: {
+        /**
+         * Start a cooling-off period (blocks gameplay + deposits; login and
+         * withdrawals stay). Extend-only — a shorter period than the active one is
+         * a `ConflictError`.
+         */
+        coolOff: (period: CoolOffPeriod) => Promise<{
+            success: true;
+            until: string;
+        }>;
+        /**
+         * Self-exclude. Irreversible player-side; revokes every session (including
+         * this one). `until` is null for `"permanent"`.
+         */
+        selfExclude: (period: SelfExclusionPeriod) => Promise<{
+            success: true;
+            until: string | null;
+        }>;
+        /** Acknowledge a reality-check prompt (audit trail only). */
+        acknowledgeRealityCheck: (gameSessionId?: string) => Promise<{
+            success: true;
+        }>;
+    };
+    /** Presence signals. */
+    readonly presence: {
+        /**
+         * Tell the runtime this player is still here (`POST
+         * /player/presence/heartbeat`, 204). Any authenticated request already
+         * refreshes presence server-side — call this only for clients that idle
+         * while "in play" (e.g. a game iframe generates provider callbacks, not
+         * player API traffic). Best-effort on the server: a storage blip never
+         * fails the request; presence decays via TTL and heals on the next call.
+         */
+        heartbeat: () => Promise<void>;
+    };
+    /** Account lifecycle. */
+    readonly account: {
+        /**
+         * Close the account (idempotent). Requires zero balances and no pending
+         * withdrawal — otherwise `ConflictError` with code `BALANCE_REMAINING` or
+         * `WITHDRAWAL_PENDING`. Revokes every session.
+         */
+        close: (reason?: string) => Promise<{
+            success: true;
+        }>;
+        /**
+         * Request a GDPR data export (202; one active at a time — a second request
+         * while pending/processing is a `ConflictError`). The download link is
+         * delivered out-of-band.
+         */
+        requestDataExport: () => Promise<DataExportStatus>;
+        /** Latest export request, or `{ status: "none" }` if never requested. */
+        dataExportStatus: () => Promise<DataExportStatus>;
+    };
+}
+
+/**
+ * `sdk.realtime` — the realtime gateway, pre-wired with the ticket handshake.
+ *
+ * Flow: `POST /realtime/ticket` (cookie-authenticated, via the HTTP layer) →
+ * `{ ticket }` → open the WS → send `{ type: "auth", token }`. In the browser the
+ * same-site HttpOnly cookie can authenticate the upgrade directly; the ticket path
+ * is used everywhere for portability and to survive access-token expiry.
+ *
+ * This is a thin delegate over the standalone {@link createRealtimeClient} so it
+ * shares the SDK's session/config and you don't pass `url`/`getAuthCredential`.
+ */
+
+/** Realtime options you can pass to `createCasinoClient({ realtime })`. */
+interface RealtimeOptions {
+    /** Reconcile missed state after every (re)connect; the SDK calls this for you. */
+    resync?: (ctx: {
+        since?: string;
+    }) => Promise<void>;
+    backoff?: {
+        baseMs?: number;
+        maxMs?: number;
+        factor?: number;
+    };
+    heartbeatMs?: number;
+    dedupeWindow?: number;
+    /** Node only: pass `ws` (`import WebSocket from "ws"`). */
+    WebSocketImpl?: WebSocketImpl;
+}
+declare class RealtimeModule {
+    private readonly http;
+    private readonly wsUrl;
+    private readonly options;
+    private client;
+    constructor(http: HttpClient, wsUrl: string, options?: RealtimeOptions);
+    /** Fetch a single-use socket ticket from the gateway. */
+    ticket(): Promise<{
+        ticket: string;
+        expiresIn: number;
+    }>;
+    private ensure;
+    get state(): ConnectionState;
+    /** Open the socket and authenticate. Call once after login. */
+    connect(): Promise<void>;
+    /** Close intentionally (call on logout). Stops auto-reconnect. */
+    disconnect(): Promise<void>;
+    /** Subscribe to a channel with a typed handler. Returns an unsubscribe fn. */
+    on<C extends RealtimeChannel>(channel: C, handler: (event: ChannelEventMap[C]) => void): Unsubscribe;
+    subscribe(channels: readonly RealtimeChannel[]): Promise<void>;
+    unsubscribe(channels: readonly RealtimeChannel[]): Promise<void>;
+    withSubscription<T>(channels: readonly RealtimeChannel[], scope: () => Promise<T>): Promise<T>;
+    activeChannels(): readonly RealtimeChannel[];
+    onStateChange(handler: (state: ConnectionState) => void): Unsubscribe;
+    onError(handler: (error: RealtimeError) => void): Unsubscribe;
+}
+
+/**
+ * `createCasinoClient` — the framework-agnostic entry point.
+ *
+ * Composes the HTTP layer + session cache + every module into one object:
+ * `{ auth, cashier, wallet, catalog, games, player, realtime, ... }`. Construct it
+ * once and share it (e.g. via the React `CasinoProvider`).
+ */
+
+interface CreateCasinoClientConfig extends CasinoClientConfig {
+    /** Options for `sdk.realtime` (resync hook, backoff, Node WebSocket, …). */
+    realtime?: RealtimeOptions;
+}
+interface CasinoClient {
+    readonly affiliate: AffiliateModule;
+    readonly auth: AuthModule;
+    readonly cashier: CashierModule;
+    readonly wallet: WalletModule;
+    readonly catalog: CatalogModule;
+    /**
+     * Plugin actions: `sdk.ext(pluginKey).call(actionKey, input)` plus catalog
+     * discovery (`sdk.ext.catalog()` / `sdk.ext.plugin(key)`).
+     */
+    readonly ext: ExtModule;
+    readonly games: GamesModule;
+    /** Player-side KYC: status, requirements, document upload, submit. */
+    readonly kyc: KycModule;
+    readonly player: PlayerModule;
+    readonly realtime: RealtimeModule;
+    /** A snapshot of the cached player/profile/currency (no network call). */
+    getSession(): SessionSnapshot;
+    /**
+     * A fully isolated scope of this client bound to `jar`: same configuration, fresh
+     * HTTP pipeline, fresh session cache — nothing (cookies, CSRF, cached player) is
+     * shared with this client or any other scope.
+     *
+     * THE way to use the SDK server-side (Next.js route handlers, RSC, API routes):
+     * a module-scope client is safe in the browser (one user per tab) but on a server
+     * it is shared across every user's requests, so its jar would replay user A's
+     * auth cookies on user B's request. Create one scope per incoming request:
+     *
+     * ```ts
+     * const scoped = client.withCookies(new CookieJar());
+     * await scoped.auth.login(credentials); // cookies stay inside this scope
+     * ```
+     */
+    withCookies(jar: CookieJar): CasinoClient;
+}
+declare function createCasinoClient(config: CreateCasinoClientConfig): CasinoClient;
+
+export { InsufficientFundsError as $, type AffiliateSubIds as A, type BalanceResponse as B, COOKIE as C, type DataExportStatus as D, type ExtActionInput as E, type ExtActionShape as F, type ExtCallArgs as G, type ExtCallOpts as H, type ExtCatalog as I, type ExtCatalogOptions as J, type ExtCatalogPlugin as K, type ExtMethod as L, type ExtModule as M, type ExtPluginClient as N, type ExtRegistry as O, type ExtRequestInit as P, type FetchLike as Q, FlowDelegatedError as R, ForbiddenError as S, type Game as T, type GameFeatures as U, type GamePage as V, type GameSession as W, type GameSessionsPage as X, type GeoQuery as Y, HEADER as Z, type HistoryRangeQuery as _, type AppErrorEnvelope as a, type SocialProvider as a$, type KycChecklistItem as a0, type KycDocumentStatus as a1, type KycHistoryEntry as a2, type KycHistoryPage as a3, type KycItemDocument as a4, type KycRequest as a5, type KycRequestStatus as a6, type KycStatusResponse as a7, type KycTrigger as a8, type KycUploadInput as a9, type PlayerPreferences as aA, type PlayerProfile as aB, type PlayerProfileRecord as aC, type PlayerStatus as aD, type PluginActionDescriptor as aE, PluginActionNotFoundError as aF, type PluginFrontendDecl as aG, PluginNotEnabledError as aH, PluginUnavailableError as aI, PluginVersionMismatchError as aJ, type ProfileResponse as aK, type Provider as aL, RateLimitError as aM, type RealtimeOptions as aN, RgBlockedError as aO, type SafeSession as aP, type SearchQuery as aQ, type SelfExclusionPeriod as aR, ServerError as aS, type SessionHistoryPage as aT, type SessionHistoryQuery as aU, type SessionSnapshot as aV, type SetLimitInput as aW, type SetPreferencesInput as aX, type SignupAttribution as aY, type SignupInput as aZ, type SocialAccount as a_, type KycUploadResult as aa, type LaunchInput as ab, type LaunchResult as ac, type LedgerEntry as ad, type LedgerQuery as ae, LimitExceededError as af, type LimitKind as ag, type LimitPeriod as ah, type LobbyQuery as ai, type LoginAttempt as aj, type LoginHistoryPage as ak, type LoginInput as al, MONEY_SCALE as am, type MeResponse as an, type MinorUnits as ao, NetworkError as ap, NotFoundError as aq, NotImplementedError as ar, type OddsFormat as as, OperationDeniedError as at, type PageInfo as au, type Paginated as av, type PaymentMethod as aw, type Player as ax, type PlayerKycStatus as ay, type PlayerLimit as az, AuthError as b, type SocialStartOptions as b0, type TrackClickInput as b1, type TrackClickResult as b2, type TransactionStatus as b3, type TransactionType as b4, type TransactionsQuery as b5, type TypedExtPluginClient as b6, UnprocessableError as b7, type UpdateProfileInput as b8, type UpdateProfileResult as b9, type UtmParams as ba, ValidationError as bb, type VerificationRequestResult as bc, type WalletBucketName as bd, type WalletBuckets as be, type WalletTransaction as bf, type WithdrawalDetail as bg, type WithdrawalHistoryPage as bh, type WithdrawalHistoryQuery as bi, type WithdrawalInput as bj, type WithdrawalResult as bk, type WithdrawalSummary as bl, type WithdrawalTxStatus as bm, assertLaunchUrl as bn, assertPluginVersion as bo, createCasinoClient as bp, decimalToMinor as bq, formatMoney as br, isAppErrorEnvelope as bs, minorStringToMinor as bt, minorToAmount as bu, minorToDecimal as bv, type AuthSession as c, type Bet as d, type BetDetail as e, type BetStatus as f, type BetsPage as g, type BetsQuery as h, type CasinoClient as i, type CasinoClientConfig as j, CasinoSdkError as k, type CategoryNode as l, ConflictError as m, type ConsentEntry as n, type ConsentsPage as o, CookieJar as p, type CoolOffPeriod as q, type CreateCasinoClientConfig as r, type DepositDetail as s, type DepositHistoryPage as t, type DepositHistoryQuery as u, type DepositInput as v, type DepositResult as w, type DepositSummary as x, type DepositTxStatus as y, type ExtActionOutput as z };