@hizi.io/engine-sdk

Type-safe TypeScript SDK for game frontends to talk to the hizi engine. Handles login, configuration loading, bet placement, multi-step rounds, win collection, provably-fair round verification, and optional WebSocket transport.

Install

npm install @hizi.io/engine-sdk

Available on npm: https://www.npmjs.com/package/@hizi.io/engine-sdk

Quick start

import { login, loadConfig, placeBet, collect } from '@hizi.io/engine-sdk';

const params = new URLSearchParams(window.location.search);
const loginResponse = await login({
  loginURL: params.get('login')!,
  launchToken: params.get('token')!,
});
const { token, backendURL } = loginResponse.result;

const configResponse = await loadConfig({ backendURL, token });
const config = configResponse.result.config;

let betResponse = await placeBet({ backendURL, token, stake: config.stakes[0] });
let gameResult = betResponse.result.result;

while (gameResult.engineData.inProgress) {
  betResponse = await placeBet({ backendURL, token });
  gameResult = betResponse.result.result;
}

// Games without wager features auto-end the round and credit winnings.
// Games with wager features keep the round open until you collect.
if (gameResult.engineData.canCollect) {
  await collect({ backendURL, token });
}

Endpoints

| Function | Purpose | | --------------------------------------------------- | ---------------------------------------------------------------- | | login({ loginURL, launchToken }) | Exchange the launch token for a session token + gameSettings | | loadConfig({ backendURL, token }) | Get game config (stakes, RTP, buy features, wager features, …) | | placeBet({ backendURL, token, stake?, ... }) | Place a bet, continue a multi-step round, or buy a feature | | collect({ backendURL, token, amount? }) | Collect winnings (only for games with wager features) | | pfVerify({ backendURL, token, serverSeed, ... }) | Replay a past PF round from its revealed seeds + player actions | | refresh(refreshURL) | Refresh the session token | | reportAnimationEnd({ backendURL, token }) | Notify backend that animation finished | | updateBalance({ backendURL, token }) | Request an updated balance | | getFreePlaysRemaining(...) / getFreePlayStake(...) | Helpers for free-play tickets | | enableWebSockets(webSocketURL) | Switch to WebSocket transport (lower latency) |

Error handling

All functions return TNetworkResponse<T> — always check success:

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;

Build

npm install
npm run build   # tsc → lib/

Development

Watch mode (rebuilds on save):

npm run dev     # tsc --watch

License

ISC