@hizi.io/engine-sdk 0.1.9

package/README.md

@@ -0,0 +1,212 @@
+# @hizi.io/engine-sdk
+
+Type-safe SDK for game frontends to communicate with the [hizi engine](https://code.hoelle.games/hizi/hizi-engine). Provides helper functions for login, configuration loading, bet placement, and win collection via the Hizi RGS platform.
+
+## Installation
+
+```bash
+npm install @hizi.io/engine-sdk
+```
+
+## Quick Start
+
+```typescript
+import { login, loadConfig, placeBet, collect } from '@hizi.io/engine-sdk';
+
+// 1. Login — exchange launch token for session token
+const params = new URLSearchParams(window.location.search);
+const loginResponse = await login({
+  loginURL: params.get('login'),
+  launchToken: params.get('token'),
+});
+const { token, backendURL } = loginResponse.result;
+
+// 2. Load game configuration
+const configResponse = await loadConfig({ backendURL, token });
+const config = configResponse.result.config;
+
+// 3. Place a bet
+const betResponse = await placeBet({ backendURL, token, stake: config.stakes[0] });
+const gameResult = betResponse.result.result;
+
+console.log('Scenario:', gameResult.scenario); // your game-specific data
+console.log('Win:', gameResult.totalWin); // win multiplier
+
+// 4. Handle multi-step rounds
+while (gameResult.engineData.inProgress) {
+  const next = await placeBet({ backendURL, token });
+  gameResult = next.result.result;
+}
+
+// 5. Collect winnings (only for games with wager features)
+if (config.wagerFeatures?.length) {
+  await collect({ backendURL, token });
+}
+```
+
+## How It Works
+
+```
+Game Frontend  ↔  HTTP/WebSocket  ↔  Hizi RGS  ↔  hizi engine  ↔  .db file
+```
+
+The backend handles outcome selection, balance management, authentication, and game state. Your frontend makes API calls and renders results.
+
+## Endpoints
+
+| Function                                    | Description                                  |
+| ------------------------------------------- | -------------------------------------------- |
+| `login({ loginURL, launchToken })`          | Exchange launch token for a session token    |
+| `loadConfig({ backendURL, token })`         | Get game config (stakes, RTP, buy-features)  |
+| `placeBet({ backendURL, token, stake? })`   | Place a bet or continue a multi-step round   |
+| `collect({ backendURL, token, amount? })`   | Collect winnings after a round completes     |
+| `refresh(refreshURL)`                       | Refresh the session token                    |
+| `reportAnimationEnd({ backendURL, token })` | Notify backend that animation finished       |
+| `updateBalance({ backendURL, token })`      | Request an updated balance                   |
+| `enableWebSockets(webSocketURL)`            | Enable WebSocket transport for lower latency |
+
+## Game Flow
+
+### 1. Login
+
+Games are launched with URL parameters containing a login URL and short-lived token:
+
+```typescript
+const loginURL = new URLSearchParams(window.location.search).get('login');
+const launchToken = new URLSearchParams(window.location.search).get('token');
+const response = await login({ loginURL, launchToken });
+const { token, backendURL } = response.result;
+```
+
+### 2. Load Configuration
+
+```typescript
+const response = await loadConfig({ backendURL, token });
+const config = response.result.config;
+// config.stakes — available stake amounts
+// config.rtp — return to player percentage
+// config.buyFeatures — available buy-feature options
+// config.wagerFeatures — available wager features (if any)
+```
+
+### 3. Place a Bet
+
+```typescript
+const response = await placeBet({ backendURL, token, stake: stakeAmount });
+const gameResult = response.result.result;
+```
+
+### 4. Handle Multi-step Rounds
+
+If `engineData.inProgress` is `true`, the round isn't complete. Keep calling `placeBet` to continue:
+
+```typescript
+if (gameResult.engineData.inProgress) {
+  const next = await placeBet({ backendURL, token });
+}
+```
+
+This happens for multi-result scenarios, free spins, and bonus features.
+
+### 5. Player Choices
+
+When `engineData.playerChoice` is set, present options to the player and send the selection:
+
+```typescript
+if (gameResult.engineData.playerChoice) {
+  const chosenIndex = await presentChoiceUI(gameResult.engineData.playerChoice);
+  await placeBet({
+    backendURL,
+    token,
+    playerChoiceIndex: chosenIndex,
+  });
+}
+```
+
+### 6. Buy-Features
+
+Purchase direct entry into a bonus feature:
+
+```typescript
+const feature = config.buyFeatures[0];
+await placeBet({
+  backendURL,
+  token,
+  stake: currentStake,
+  featureToBuy: feature.id,
+});
+```
+
+### 7. Collect or Continue Wager
+
+Games **without** wager features auto-end rounds and credit winnings. Games **with** wager features keep the round open so the player can collect or continue wagering:
+
+```typescript
+// Collect winnings
+await collect({ backendURL, token });
+
+// Or continue wagering (engine handles wager features via placeBet continuation)
+await placeBet({ backendURL, token });
+```
+
+## Error Handling
+
+All functions return `TNetworkResponse<T>` — always check `success`:
+
+```typescript
+const response = await placeBet({ backendURL, token, stake });
+
+if (!response.success) {
+  if (recoverableErrorCodes.includes(response.error.code)) {
+    // Retry-able: balance too low, rate limit, network error
+  } else {
+    // Fatal: refresh the game
+  }
+  return;
+}
+
+const gameResult = response.result.result;
+```
+
+## WebSocket Support
+
+Enable WebSocket transport for lower latency — all subsequent calls automatically route through it:
+
+```typescript
+import { enableWebSockets } from '@hizi.io/engine-sdk';
+const wsHandler = await enableWebSockets(webSocketURL);
+```
+
+## Key Types
+
+```typescript
+import type {
+  IGameResult, // Game result with scenario data and engine state
+  ILoadConfigConfig, // Game configuration (stakes, RTP, buy-features)
+  IScenarioInfo, // Multi-result scenario progression
+  ISpinInfo, // Free spin / bonus feature tracking
+  IBuyFeatureOption, // Buy-feature definition
+  IPlaceBetReply, // placeBet response
+  ICollectReply, // collect response
+  ILoadConfigReply, // loadConfig response
+  IConnectReply, // login/refresh response
+  TNetworkResponse, // Success | Error wrapper
+  IGameSettings, // Platform game settings
+  IGameRoundInfo, // Round status
+  IFreePlayInfo, // Free play info
+  WebSocketHandler, // WebSocket controller
+  ISessionOptions, // Common { backendURL, token } options
+  ILoginOptions, // login() options
+  IPlaceBetOptions, // placeBet() options
+  ICollectOptions, // collect() options
+} from '@hizi.io/engine-sdk';
+```
+
+## Related Projects
+
+| Repo                                                               | Description                      |
+| ------------------------------------------------------------------ | -------------------------------- |
+| [hizi-engine](https://code.hoelle.games/hizi/hizi-engine)             | Runtime server                   |
+| [hizi-generator-ts](https://code.hoelle.games/hizi/hizi-generator-ts) | .db file generation (TypeScript) |
+| [hizi-engine-tester](https://code.hoelle.games/hizi/hizi-engine-tester) | Web-based testing UI             |
+| [hizi-engine-docs](https://code.hoelle.games/hizi/hizi-engine-docs)     | Full documentation               |

package/lib/api.d.ts

@@ -0,0 +1,198 @@
+import type { TNetworkResponse, IConnectReply, ILoadConfigReply, IPlaceBetReply, ICollectReply, IBalanceReply, IFreePlayInfo, IPfVerifyReply, ISessionOptions, ILoginOptions, IPlaceBetOptions, ICollectOptions, IPfVerifyOptions } from './types/index.js';
+/**
+ * Exchange a launch token for a session token.
+ *
+ * The `loginURL` and `launchToken` are provided as URL query parameters
+ * when the game is launched by the operator.
+ *
+ * @param options - Login credentials from the launch URL.
+ * @param options.loginURL - The operator-provided login endpoint URL.
+ * @param options.launchToken - Short-lived token from the launch URL query string.
+ * @returns A session token, backend URL, and platform settings on success.
+ *
+ * @example
+ * ```ts
+ * const response = await login({ loginURL, launchToken });
+ * if (response.success) {
+ *   const { token, backendURL } = response.result;
+ * }
+ * ```
+ */
+export declare function login(options: ILoginOptions): Promise<TNetworkResponse<IConnectReply>>;
+/**
+ * Load the game configuration including available stakes, RTP, and buy features.
+ *
+ * Call this once after {@link login} to retrieve the game's configuration before
+ * placing any bets. If a previous round was interrupted, the response includes
+ * `gameResult` and `amountToCollect` for resumption.
+ *
+ * @param options - Session credentials from the login response.
+ * @param options.backendURL - Backend URL from the login response.
+ * @param options.token - Session token.
+ * @returns Game configuration, balance, and any in-progress round data.
+ *
+ * @example
+ * ```ts
+ * const response = await loadConfig({ backendURL, token });
+ * if (response.success) {
+ *   const { stakes, rtp, buyFeatures } = response.result.config;
+ * }
+ * ```
+ */
+export declare function loadConfig(options: ISessionOptions): Promise<TNetworkResponse<ILoadConfigReply>>;
+/**
+ * Place a bet and receive a game result, or continue an in-progress round.
+ *
+ * - **New spin** — pass the desired `stake` amount.
+ * - **Continue round** — omit `stake` when `engineData.inProgress` is `true`.
+ * - **Buy feature** — pass `featureToBuy` to enter a bonus directly (engine computes the price).
+ * - **Player choice** — pass `playerChoiceIndex` when `engineData.playerChoice` is set.
+ *
+ * @param options - Bet parameters.
+ * @param options.backendURL - Backend URL from the login response.
+ * @param options.token - Session token.
+ * @param options.stake - Stake amount in minor currency units. Required for the first call of a game round.
+ * @param options.featureToBuy - Buy-feature ID (e.g. `'freespin'`).
+ * @param options.playerChoiceIndex - Index of the selected option when `engineData.playerChoice` is set.
+ * @param options.useTicket - Set `true` to consume a free play ticket.
+ * @param options.useTicketFeatureType - Feature type of the free play ticket.
+ * @param options.additionalData - Additional game-specific parameters.
+ * @returns The game result including scenario data, engine state, and cumulative win.
+ *
+ * @example
+ * ```ts
+ * // New spin
+ * const response = await placeBet({ backendURL, token, stake });
+ *
+ * // Buy feature
+ * const response = await placeBet({ backendURL, token, stake, featureToBuy: 'freespin' });
+ *
+ * // Continue round
+ * const response = await placeBet({ backendURL, token });
+ * ```
+ */
+export declare function placeBet(options: IPlaceBetOptions): Promise<TNetworkResponse<IPlaceBetReply>>;
+/**
+ * Collect winnings after a completed round.
+ *
+ * Only available for games with wager features (`config.wagerFeatures` is present).
+ * Games without wager features auto-end the round and credit winnings automatically.
+ *
+ * @param options - Session credentials and optional partial amount.
+ * @param options.backendURL - Backend URL from the login response.
+ * @param options.token - Session token.
+ * @param options.amount - Amount to collect. Omit to collect the full available amount.
+ * @returns The credited amount and updated balance.
+ * @throws When called on a game without wager features, or when no winnings are available.
+ *
+ * @example
+ * ```ts
+ * if (gameResult.engineData.canCollect) {
+ *   const response = await collect({ backendURL, token });
+ * }
+ * ```
+ */
+export declare function collect(options: ICollectOptions): Promise<TNetworkResponse<ICollectReply>>;
+/**
+ * Re-run a past round against its revealed PF seeds and get back the
+ * engine's offline replay — the per-call RNG audit (`rngData`) and the
+ * per-step game outcomes (`steps`) — so the caller can diff them against
+ * what they recorded live.
+ *
+ * Only meaningful for rounds played with `config.rng === 'pf'`. The
+ * endpoint never touches the wallet, progression counters, or operator
+ * caps; it's pure compute.
+ *
+ * Two checks make up a passing verification:
+ *
+ * 1. **Audit replay** — `reply.rngData` matches the live `pf.rngData`
+ *    element-wise. A swapped server seed would yield different draws, so
+ *    this transitively proves the revealed seed is the one committed to.
+ * 2. **Result replay** — `reply.steps[i].scenario` / `totalWin` match the
+ *    live round at each step. The terminal step is `steps[steps.length - 1]`.
+ *
+ * @param options - Verify parameters; see {@link IPfVerifyOptions}.
+ * @param options.backendURL - Backend URL from the login response.
+ * @param options.token - Session token (used to resolve the game config).
+ * @param options.serverSeed - Revealed server seed from the round's `pf` block.
+ * @param options.clientSeed - Client seed bound to the round.
+ * @param options.startNonce - Defaults to `0`. Set when the round opened mid-PF-session.
+ * @param options.stake - Stake the round opened with (required by games that need it to settle).
+ * @param options.featureToBuy - Buy-feature id the round opened on, if any.
+ * @param options.initialData - Mirror the round's opening payload (blackjack side bets, …).
+ * @param options.bets - Roulette / crash opening bets.
+ * @param options.playerNumbers - Keno picks, if the player chose their own.
+ * @param options.actions - Continuation actions in order; shape per game (see {@link IPfVerifyAction}).
+ *
+ * @example
+ * ```ts
+ * // Verify a one-shot roulette round.
+ * const reply = await pfVerify({
+ *   backendURL, token,
+ *   serverSeed: pf.revealedServerSeed,
+ *   clientSeed: pf.clientSeed,
+ *   stake: 200,
+ *   bets: [{ type: 'straight', selection: 17, stake: 100 }, { type: 'red', stake: 100 }],
+ * });
+ * if (reply.success) {
+ *   const rngOk = deepEqual(reply.result.rngData, pf.rngData);
+ *   const pocketOk = (reply.result.steps[0].scenario as { pocket: number }).pocket === liveScenario.pocket;
+ * }
+ * ```
+ */
+export declare function pfVerify(options: IPfVerifyOptions): Promise<TNetworkResponse<IPfVerifyReply>>;
+/**
+ * Refresh the session token when it expires.
+ *
+ * Call this when API requests start returning `SESSIONINVALID` or `NOTLOGGEDON`
+ * errors. The new session token and URLs are returned in the response.
+ *
+ * @param refreshURL - The refresh endpoint URL from the {@link login} response (`result.refreshURL`).
+ * @returns A new session token and updated platform info.
+ *
+ * @example
+ * ```ts
+ * const response = await refresh(refreshURL);
+ * if (response.success) {
+ *   token = response.result.token;
+ * }
+ * ```
+ */
+export declare function refresh(refreshURL: string): Promise<TNetworkResponse<IConnectReply>>;
+/**
+ * Report that the game animation has finished playing.
+ *
+ * Only needed when `gameSettings.reportAnimationEnd` is `true` (set by the operator).
+ * Call this after your spin/win animation completes.
+ *
+ * @param options - Session credentials.
+ * @param options.backendURL - Backend URL from the login response.
+ * @param options.token - Session token.
+ */
+export declare function reportAnimationEnd(options: ISessionOptions): Promise<TNetworkResponse<void>>;
+/**
+ * Request an updated balance from the server.
+ *
+ * Use this to refresh the displayed balance outside of the normal
+ * `placeBet`/`collect` flow (e.g. after an external deposit).
+ *
+ * @param options - Session credentials.
+ * @param options.backendURL - Backend URL from the login response.
+ * @param options.token - Session token.
+ * @returns The player's current balance.
+ */
+export declare function updateBalance(options: ISessionOptions): Promise<TNetworkResponse<IBalanceReply>>;
+/**
+ * Get the total number of free plays remaining.
+ *
+ * @param freePlaysAvailable - The `freePlaysAvailable` array from a `loadConfig` or `placeBet` response.
+ * @returns Total free play count across all entries, or `0` if none available.
+ */
+export declare function getFreePlaysRemaining(freePlaysAvailable?: IFreePlayInfo[]): number;
+/**
+ * Get the stake amount for available free plays.
+ *
+ * @param freePlaysAvailable - The `freePlaysAvailable` array from a `loadConfig` or `placeBet` response.
+ * @returns The first free play's stake amount, or `undefined` if none available.
+ */
+export declare function getFreePlayStake(freePlaysAvailable?: IFreePlayInfo[]): number | undefined;