@hizi.io/engine-sdk 0.1.9

package/lib/types/replies.d.ts

@@ -0,0 +1,107 @@
+import type { IBalanceReply } from './balance.js';
+import type { IGameSettings } from './gameSettings.js';
+import type { ITokenData } from './tokenData.js';
+import type { IFreePlayInfo } from './freePlayInfo.js';
+import type { ILoadConfigConfig } from './loadConfigConfig.js';
+import type { IGameResult } from './gameResult.js';
+import type { IGameRoundInfo } from './gameRoundInfo.js';
+/** Response from `login()` and `refresh()` containing the session token and platform info. */
+export interface IConnectReply {
+    /** Session token for all subsequent API calls. */
+    token: string;
+    /** Base URL for game API requests. */
+    backendURL: string;
+    /** URL for refreshing an expired session token. */
+    refreshURL: string;
+    /** URL for logging out the session. */
+    logoutURL: string;
+    /** Optional WebSocket URL for lower-latency communication. */
+    webSocketURL?: string;
+    /** Player's current balance. */
+    balance?: IBalanceReply;
+    /** Platform settings (feature toggles and limits). */
+    gameSettings?: IGameSettings;
+    /** Opaque session metadata. */
+    tokenData?: ITokenData;
+    /** Operator-granted free plays. */
+    freePlaysAvailable?: IFreePlayInfo[];
+}
+/** Response from `loadConfig()` containing game configuration and round resumption data. */
+export interface ILoadConfigReply {
+    /** Game configuration (stakes, RTP, buy-features, wager features). */
+    config: ILoadConfigConfig;
+    /** Updated session metadata. */
+    tokenData: ITokenData;
+    /** Player's current balance. */
+    balance?: IBalanceReply;
+    /** Last game result, present when resuming an incomplete round. */
+    gameResult?: IGameResult;
+    /** Round info, present when resuming an incomplete round. */
+    gameRoundInfo?: IGameRoundInfo;
+    /** Operator-granted free plays. */
+    freePlaysAvailable?: IFreePlayInfo[];
+    /** Previous game results for history display. */
+    previousResults?: IGameResult[];
+    /** Uncollected win amount from a prior incomplete round. */
+    amountToCollect?: number;
+}
+/** Response from `placeBet()` containing the game result. */
+export interface IPlaceBetReply {
+    /** The game result with scenario data and engine state. */
+    result: IGameResult;
+    /** Updated session metadata. */
+    tokenData: ITokenData;
+    /** Updated player balance. */
+    balance?: IBalanceReply;
+    /** Current round status. */
+    gameRoundInfo?: IGameRoundInfo;
+    /** Uncollected win amount available for `collect()`. */
+    amountToCollect?: number;
+}
+/** Response from `collect()` confirming winnings collection. */
+export interface ICollectReply {
+    /** Amount credited to the player's balance. */
+    amountCredited: number;
+    /** Amount that was requested for collection. */
+    amountToCollect: number;
+    /** Updated player balance. */
+    balance?: IBalanceReply;
+    /** Updated session metadata. */
+    tokenData: ITokenData;
+}
+/**
+ * One row of the per-round RNG audit trail. Mirrors the shape on the live
+ * `pf.rngData` block so a `pfVerify` reply can be diffed against the saved
+ * live audit element-for-element.
+ *
+ * - `'double'` rows carry the raw HMAC float in `[0, 1)` — compare directly.
+ * - `'int'` rows carry an integer the engine mapped from the float; compare
+ *   by exact equality.
+ *
+ * `id` is `pf:start-end` for PF rounds (the nonce range the batch covers).
+ */
+export interface IRngDataEntry {
+    id: string;
+    values: number[];
+    nonces?: number[];
+    type?: 'int' | 'double';
+}
+/** Response from `pfVerify()` — the offline replay's audit + per-step outcomes. */
+export interface IPfVerifyReply {
+    /**
+     * Per-call RNG audit. Diff element-wise against the round's saved
+     * `pf.rngData` — a passing diff is the proof that the engine drew the
+     * values it claimed and that the revealed `serverSeed` is the one
+     * committed to (a swapped seed would yield different draws).
+     */
+    rngData: IRngDataEntry[];
+    /**
+     * Per-step `IGameResult`s in order; the terminal step is the last
+     * element. Length 1 for one-shot rounds (roulette / keno / slot / crash
+     * / …), longer for multi-step (blackjack / mines / hi-lo / …). Compare
+     * each `scenario` / `totalWin` to the live round; `engineData` carries
+     * flow-control state (`playerChoice`, `inProgress`, …) for callers
+     * that want to verify the round's flow too.
+     */
+    steps: IGameResult[];
+}

package/lib/types/replies.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/roulette.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Roulette-specific payloads carried through `IPlaceBetOptions.additionalData`
+ * and returned in `IGameResult.scenario`.
+ */
+export type TRouletteBetType = 'straight' | 'split' | 'street' | 'corner' | 'six_line' | 'red' | 'black' | 'odd' | 'even' | 'low_18' | 'high_18' | 'dozen' | 'column';
+export type TRouletteEvenMoneyBetType = 'red' | 'black' | 'odd' | 'even' | 'low_18' | 'high_18';
+/** Bet selection shape by type. */
+export type TRouletteBetSelection = {
+    type: 'straight';
+    selection: number;
+} | {
+    type: 'split';
+    selection: [number, number];
+} | {
+    type: 'street';
+    selection: number;
+} | {
+    type: 'corner';
+    selection: [number, number, number, number];
+} | {
+    type: 'six_line';
+    selection: number;
+} | {
+    type: 'dozen' | 'column';
+    selection: 1 | 2 | 3;
+} | {
+    type: TRouletteEvenMoneyBetType;
+    selection?: null;
+};
+export type IRouletteBet = TRouletteBetSelection & {
+    stake: number;
+};
+export type IRouletteBetSettlement = TRouletteBetSelection & {
+    stake: number;
+    won: boolean;
+    payout: number;
+    winAmount: number;
+};
+export interface IRouletteScenario {
+    pocket: number;
+    color: 'red' | 'black' | 'green';
+    oddEven: 'odd' | 'even' | null;
+    highLow: 'low_18' | 'high_18' | null;
+    dozen: 1 | 2 | 3 | null;
+    column: 1 | 2 | 3 | null;
+    settlement: IRouletteBetSettlement[];
+    totalStake: number;
+    totalWin: number;
+}
+/** Build a `placeBet` additionalData payload for a roulette round. */
+export declare function rouletteAdditionalData(bets: IRouletteBet[]): {
+    bets: IRouletteBet[];
+};

package/lib/types/roulette.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Roulette-specific payloads carried through `IPlaceBetOptions.additionalData`
+ * and returned in `IGameResult.scenario`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rouletteAdditionalData = rouletteAdditionalData;
+/** Build a `placeBet` additionalData payload for a roulette round. */
+function rouletteAdditionalData(bets) {
+    return { bets };
+}

package/lib/types/scenarioInfo.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tracks progression through a multi-result scenario (e.g. cascades, tumbles).
+ * Each `placeBet` call advances to the next scenario step.
+ */
+export interface IScenarioInfo {
+    /** Index of the randomly selected scenario from the entry's scenario pool. */
+    scenarioIndex: number;
+    /** Current step within the scenario (0-based, increments per `placeBet` continuation). */
+    currentScenarioIndex: number;
+    /** Whether there are more scenario steps to play. */
+    inProgress: boolean;
+}

package/lib/types/scenarioInfo.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/sessionOptions.d.ts

@@ -0,0 +1,7 @@
+/** Common options for all authenticated game API calls. */
+export interface ISessionOptions {
+    /** Backend URL from the {@link login} response. */
+    backendURL: string;
+    /** Session token from the {@link login} or {@link refresh} response. */
+    token: string;
+}

package/lib/types/sessionOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/spinAward.d.ts

@@ -0,0 +1,31 @@
+/**
+ * One option in a player choice prompt (e.g. "pick 5 or 10 free spins").
+ * Present in `IGameResult.engineData.playerChoice` when the engine
+ * is waiting for the player to select before continuing.
+ */
+export type TPlayerChoiceFeatureAward = {
+    /** Number of spins awarded if this option is selected. */
+    count: number;
+    /** Target feature DB for the awarded spins (e.g. "freespin"). */
+    feature: string;
+};
+/**
+ * Cash option in a player choice prompt — selecting this pays the player
+ * `winMultiplier × stake` directly, with no feature spin awarded.
+ * Present in `IGameResult.engineData.playerChoice` when a cash-awarding
+ * progression counter completed via `playerChoice` selection.
+ */
+export type TPlayerChoiceCashAward = {
+    /** Cash payout as a multiplier of the player's stake. */
+    winMultiplier: number;
+};
+/**
+ * A single option in a `playerChoice` prompt — either a feature-spin award
+ * or a cash award. Cash options are only ever introduced via progression
+ * counter completions.
+ */
+export type TPlayerChoiceAward = TPlayerChoiceFeatureAward | TPlayerChoiceCashAward;
+/** Type guard: is this player choice option a cash award? */
+export declare function isCashChoice(award: TPlayerChoiceAward): award is TPlayerChoiceCashAward;
+/** Type guard: is this player choice option a feature-spin award? */
+export declare function isFeatureChoice(award: TPlayerChoiceAward): award is TPlayerChoiceFeatureAward;

package/lib/types/spinAward.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCashChoice = isCashChoice;
+exports.isFeatureChoice = isFeatureChoice;
+/** Type guard: is this player choice option a cash award? */
+function isCashChoice(award) {
+    return award.winMultiplier !== undefined;
+}
+/** Type guard: is this player choice option a feature-spin award? */
+function isFeatureChoice(award) {
+    return award.feature !== undefined;
+}

package/lib/types/spinInfo.d.ts

@@ -0,0 +1,9 @@
+/** Tracks remaining and consumed spins for an active feature (e.g. free spins, bonus round). */
+export interface ISpinInfo {
+    /** Feature name identifying the DB to spin from (e.g. "freespin", "bonus"). */
+    feature: string;
+    /** Spins remaining for this feature. */
+    count: number;
+    /** Spins already consumed from this feature. */
+    used: number;
+}

package/lib/types/spinInfo.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/tokenData.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Opaque session metadata managed by the platform.
+ * Included in every API response and passed back automatically by the SDK.
+ */
+export interface ITokenData {
+    [key: string]: unknown;
+}

package/lib/types/tokenData.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/websocket.d.ts

@@ -0,0 +1,27 @@
+/** Handler returned by {@link enableWebSockets} for managing the WebSocket connection. */
+export interface WebSocketHandler {
+    /** Close the WebSocket connection and revert all API calls to HTTP. */
+    close: () => void;
+    /** Returns `true` if the WebSocket connection is open. */
+    isConnected: () => boolean;
+}
+/**
+ * Enable WebSocket communication for lower latency.
+ *
+ * Once enabled, all subsequent API calls ({@link loadConfig}, {@link placeBet},
+ * {@link collect}, etc.) automatically route through the WebSocket connection
+ * instead of HTTP.
+ *
+ * @param webSocketURL - The WebSocket URL from the {@link login} response (`result.webSocketURL`).
+ * @returns A handler to check connection status and close the socket.
+ *
+ * @example
+ * ```ts
+ * const ws = await enableWebSockets(webSocketURL);
+ * // All API calls now use WebSocket automatically
+ * const response = await placeBet({ backendURL, token, stake });
+ * // Later, to disconnect:
+ * ws.close();
+ * ```
+ */
+export declare function enableWebSockets(webSocketURL: string): Promise<WebSocketHandler>;

package/lib/websocket.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enableWebSockets = enableWebSockets;
+const constants_js_1 = require("./constants.js");
+const network_js_1 = require("./network.js");
+let requestCounter = 0;
+function decodeBase64Utf8(value) {
+    try {
+        const binary = atob(value);
+        const bytes = Uint8Array.from(binary, c => c.charCodeAt(0));
+        return new TextDecoder('utf-8').decode(bytes);
+    }
+    catch {
+        return value;
+    }
+}
+// The websocket-router forwards a successful response as
+// `{status, headers, reply, requestId}` — same shape as an HTTP response. On
+// failure it surfaces the engine error via headers (x-h-error-* mirroring the
+// HTTP path) and/or fields on `reply` (errorId / errorText / passThroughData).
+function buildErrorFromResponse(headers, reply, statusText) {
+    const h = headers ?? {};
+    const lookup = (name) => h[name] ?? h[name.toLowerCase()];
+    const errorMsgBase64 = lookup('x-h-error-msg-base64');
+    const headerMsg = errorMsgBase64 ? decodeBase64Utf8(errorMsgBase64) : lookup('x-h-error-msg');
+    const headerId = lookup('x-h-error-id');
+    const error = {
+        code: String(headerId ?? reply?.errorId ?? reply?.code ?? constants_js_1.API_RETURNCODES.UNEXPECTED),
+        message: (headerMsg ?? reply?.errorText ?? reply?.message ?? statusText),
+    };
+    const passThroughData = reply?.passThroughData;
+    if (passThroughData !== undefined && passThroughData !== 'undefined') {
+        error.passThroughData = passThroughData;
+    }
+    return error;
+}
+/**
+ * Enable WebSocket communication for lower latency.
+ *
+ * Once enabled, all subsequent API calls ({@link loadConfig}, {@link placeBet},
+ * {@link collect}, etc.) automatically route through the WebSocket connection
+ * instead of HTTP.
+ *
+ * @param webSocketURL - The WebSocket URL from the {@link login} response (`result.webSocketURL`).
+ * @returns A handler to check connection status and close the socket.
+ *
+ * @example
+ * ```ts
+ * const ws = await enableWebSockets(webSocketURL);
+ * // All API calls now use WebSocket automatically
+ * const response = await placeBet({ backendURL, token, stake });
+ * // Later, to disconnect:
+ * ws.close();
+ * ```
+ */
+async function enableWebSockets(webSocketURL) {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(webSocketURL);
+        // Router sends responses as Buffer; parse as ArrayBuffer to avoid Blob async hop.
+        ws.binaryType = 'arraybuffer';
+        const pending = new Map();
+        ws.onopen = () => {
+            const transport = {
+                send(body) {
+                    return new Promise(res => {
+                        const requestId = `ws-${++requestCounter}`;
+                        // websocket-router's incomingHandler expects this envelope; it then
+                        // re-queues `data.body` to the game's HTTP backend route, so the
+                        // engine sees the same payload it would over HTTP.
+                        const message = {
+                            cmd: 'game',
+                            data: {
+                                body,
+                                requestId,
+                                method: 'POST',
+                                headers: { 'Content-Type': 'application/json' },
+                            },
+                        };
+                        const timer = setTimeout(() => {
+                            pending.delete(requestId);
+                            res({
+                                success: false,
+                                error: {
+                                    code: String(constants_js_1.API_RETURNCODES.NETWORKERROR),
+                                    message: 'WebSocket request timed out',
+                                },
+                            });
+                        }, constants_js_1.defaultNetworkTimeout);
+                        pending.set(requestId, {
+                            resolve: res,
+                            timer,
+                        });
+                        try {
+                            ws.send(JSON.stringify(message));
+                        }
+                        catch {
+                            clearTimeout(timer);
+                            pending.delete(requestId);
+                            res({
+                                success: false,
+                                error: {
+                                    code: String(constants_js_1.API_RETURNCODES.NETWORKERROR),
+                                    message: 'WebSocket send failed',
+                                },
+                            });
+                        }
+                    });
+                },
+                isConnected() {
+                    return ws.readyState === WebSocket.OPEN;
+                },
+            };
+            (0, network_js_1.setWsTransport)(transport);
+            resolve({
+                close() {
+                    (0, network_js_1.setWsTransport)(null);
+                    for (const [, req] of pending) {
+                        clearTimeout(req.timer);
+                        req.resolve({
+                            success: false,
+                            error: {
+                                code: String(constants_js_1.API_RETURNCODES.NETWORKERROR),
+                                message: 'WebSocket connection closed',
+                            },
+                        });
+                    }
+                    pending.clear();
+                    ws.close();
+                },
+                isConnected() {
+                    return ws.readyState === WebSocket.OPEN;
+                },
+            });
+        };
+        ws.onmessage = event => {
+            try {
+                const text = typeof event.data === 'string'
+                    ? event.data
+                    : event.data instanceof ArrayBuffer
+                        ? new TextDecoder('utf-8').decode(event.data)
+                        : null;
+                if (text === null)
+                    return;
+                const data = JSON.parse(text);
+                const requestId = data.requestId;
+                if (!requestId || !pending.has(requestId))
+                    return;
+                const req = pending.get(requestId);
+                pending.delete(requestId);
+                clearTimeout(req.timer);
+                const status = data.status ?? 0;
+                if (status >= 200 && status < 300) {
+                    req.resolve({ success: true, result: data.reply ?? {} });
+                }
+                else {
+                    req.resolve({
+                        success: false,
+                        error: buildErrorFromResponse(data.headers, data.reply, `HTTP ${status}`),
+                    });
+                }
+            }
+            catch {
+                // Ignore non-JSON messages
+            }
+        };
+        ws.onclose = () => {
+            (0, network_js_1.setWsTransport)(null);
+            for (const [, req] of pending) {
+                clearTimeout(req.timer);
+                req.resolve({
+                    success: false,
+                    error: {
+                        code: String(constants_js_1.API_RETURNCODES.NETWORKERROR),
+                        message: 'WebSocket connection closed',
+                    },
+                });
+            }
+            pending.clear();
+        };
+        ws.onerror = () => {
+            if (ws.readyState !== WebSocket.OPEN) {
+                reject(new Error('WebSocket connection failed'));
+            }
+        };
+    });
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@hizi.io/engine-sdk",
+  "version": "0.1.9",
+  "description": "SDK for communicating with the hizi engine",
+  "author": "David Dunnings",
+  "license": "ISC",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "typescript": "5.8.3"
+  }
+}