@hizi.io/engine-sdk 0.1.9

package/lib/types/gameSettings.d.ts

@@ -0,0 +1,133 @@
+/** Screen orientation lock modes. */
+export declare enum ForcedOrientation {
+    none = 0,
+    landscape = 1,
+    portrait = 2
+}
+/** Win odds metrics that can be shown to the player. */
+export declare enum DisplayWinOdds {
+    maxPayout = "maxPayout",
+    maxWin = "maxWin"
+}
+/**
+ * Operator-configured platform settings controlling UI features and gameplay limits.
+ * Returned once in the `login()` response.
+ */
+export interface IGameSettings {
+    /** Whether the autoplay feature is available. */
+    autoplayEnabled: boolean;
+    /** Whether a loss limit must be set before starting autoplay. */
+    autoplayLossLimitRequired: boolean;
+    /** @deprecated Whether to show a coin-based display alongside currency. */
+    displayCoins: boolean;
+    /** Whether jackpot odds should be shown to the player. */
+    displayJackpotOdds: boolean;
+    /** Whether the RTP percentage should be shown to the player. */
+    displayRTP: boolean;
+    /** Whether the experienced RTP (for Bonus Spin games) should be shown to the player. */
+    displayXRTP: boolean;
+    /** Lock the game to a specific screen orientation. */
+    forceOrientation: ForcedOrientation;
+    /** Whether wager/gamble games (e.g. card color) are available. */
+    gambleEnabled: boolean;
+    /** URL to the player's game history page. */
+    historyURL: string;
+    /** URL to the platform home/lobby. */
+    homeURL: string;
+    /** Message displayed during game loading. */
+    loadMsg: string;
+    /** Maximum exposure per session. */
+    maxExposure: number;
+    /** Maximum allowed stake amount. */
+    maxStake: number;
+    /** Maximum allowed stake for buy-feature/package purchases. */
+    maxPackageStake: number;
+    /** Minimum allowed stake amount. */
+    minStake: number;
+    /** Minimum milliseconds to show the loading screen. */
+    minLoadTime: number;
+    /** Minimum milliseconds between spins. */
+    minSpinTime: number;
+    /** Whether multiple game instances can run simultaneously. */
+    multipleInstancesAllowed: boolean;
+    /** Whether reality-check dialog shows win/loss totals. */
+    rcDisplayWinLoss: boolean;
+    /** Whether reality-check reminders are enabled. */
+    rcEnabled: boolean;
+    /** Interval in seconds between reality-check prompts. */
+    rcInterval: number;
+    /** Whether the player can stop spinning mid-sequence. */
+    stopEnabled: boolean;
+    /** URL to the deposit/top-up page. */
+    topupURL: string;
+    /** Whether turbo/fast spin mode is available. */
+    turboEnabled: boolean;
+    /** Whether the home/lobby button should be shown. */
+    homeEnabled: boolean;
+    /** Whether min spin time adjusts dynamically based on animation length. */
+    dynamicMinSpinTime: boolean;
+    /** Browser navigation target for external links (home, history, etc.). */
+    redirectTarget: 'self' | 'parent' | 'top';
+    /** Whether buy-feature (bonus buy) is enabled. */
+    packageBuyEnabled: boolean;
+    /** Index into the stakes array for the default bet amount. */
+    defaultStakeIndex: number;
+    /** Whether the operator platform handles error display instead of the game. */
+    operatorHandlesErrors: boolean;
+    /** Whether to display a clock in the game UI. */
+    displayClock: boolean;
+    /** Whether this is a social/free-to-play (non-real-money) session. */
+    isSocial: boolean;
+    /** Whether currency symbols/codes should be displayed. */
+    displayCurrency: boolean;
+    /** Operator-defined custom stake values (overrides default stakes if non-empty). */
+    customStakes: number[];
+    /** URL to the loss-limit management page. */
+    lossLimitURL: string;
+    /** Whether the player can collect a partial win amount. */
+    partialCollectEnabled: boolean;
+    /** Whether to hide the game provider logo. */
+    hideCompanyLogo: boolean;
+    /** Whether to abbreviate large monetary amounts (e.g. 1.2K). */
+    abbreviateAmounts: boolean;
+    /** Whether to show the exact RTP value instead of a rounded one. */
+    showExactRTP: boolean;
+    /** Jurisdiction code governing regulatory behaviour. */
+    jurisdiction: string;
+    /** Whether to force the default stake on every session start. */
+    forceDefaultStake: boolean;
+    /** Whether to disable fullscreen mode on mobile devices. */
+    disableFullScreenMobile: boolean;
+    /** Whether to show the paytable automatically when the game loads. */
+    displayPaytableOnEnterGame: boolean;
+    /** Setting keys that should not be persisted between sessions. */
+    doNotStoreSettings: string[];
+    /** Session timeout duration in seconds (0 = no timeout). */
+    sessionTimeoutInSeconds: number;
+    /** Whether to display the net position (win minus loss) to the player. */
+    displayNetPosition: boolean;
+    /** Whether to hide the balance display in demo/fun mode. */
+    hideDemoBalance: boolean;
+    /** Whether to prevent automatic redirects (e.g. on session expiry). */
+    preventRedirect: boolean;
+    /** Whether the browser refresh/reload action is disabled. */
+    refreshDisabled: boolean;
+    /** Which win-odds metrics to display to the player. */
+    displayWinOdds: DisplayWinOdds[];
+    /** Whether to show a session timer, or a custom label string for it. */
+    displaySessionTimer: boolean | string;
+    /** Whether to skip win celebrations for wins equal to or less than the stake. */
+    skipWinsEqualToOrLessThanStake: boolean;
+    /** Whether `reportAnimationEnd()` must be called after each spin animation completes. */
+    reportAnimationEnd: boolean;
+    /** The launcher platform type. */
+    launcherType: 'reelLink' | 'online';
+    /** Whether autoplay UI shows total stake (stake x spins) instead of per-spin stake. */
+    autoplayShowTotalStake: boolean;
+    /** Whether error messages should be translated to the player's locale. */
+    translateErrors: boolean;
+    /** ISO 4217 currency code to display (overrides the session currency). */
+    currencyToDisplay: string;
+    /** Additional operator-specific fields. */
+    [key: string]: unknown;
+}

package/lib/types/gameSettings.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisplayWinOdds = exports.ForcedOrientation = void 0;
+/** Screen orientation lock modes. */
+var ForcedOrientation;
+(function (ForcedOrientation) {
+    ForcedOrientation[ForcedOrientation["none"] = 0] = "none";
+    ForcedOrientation[ForcedOrientation["landscape"] = 1] = "landscape";
+    ForcedOrientation[ForcedOrientation["portrait"] = 2] = "portrait";
+})(ForcedOrientation || (exports.ForcedOrientation = ForcedOrientation = {}));
+/** Win odds metrics that can be shown to the player. */
+var DisplayWinOdds;
+(function (DisplayWinOdds) {
+    DisplayWinOdds["maxPayout"] = "maxPayout";
+    DisplayWinOdds["maxWin"] = "maxWin";
+})(DisplayWinOdds || (exports.DisplayWinOdds = DisplayWinOdds = {}));

package/lib/types/gameState.d.ts

@@ -0,0 +1,20 @@
+/** Historical record of a game round transaction (bet, collect, or wager). */
+export interface IGameState {
+    /** Unique identifier for this game round. */
+    hash: string;
+    /** Transaction type (e.g. "placeBet", "collect", "wager"). */
+    type: string;
+    /** ISO timestamp of when this transaction was processed. */
+    processedOn?: string;
+    /** Result data, if the transaction produced an outcome. */
+    result?: {
+        winAmount?: number;
+        info: Record<string, unknown>;
+    };
+    /** Total amount wagered in this transaction. */
+    amountWagered?: number;
+    /** Amount collected/credited to the player. */
+    collected?: number;
+    /** Reason for this state entry (for debugging/audit). */
+    reason?: string;
+}

package/lib/types/gameState.js

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

package/lib/types/index.d.ts

@@ -0,0 +1,32 @@
+export type { TNetworkResponse, TNetworkSuccess, TNetworkError, IErrorResponse } from './network.js';
+export type { IBalanceEntry, IBalanceReply } from './balance.js';
+export type { IGameSettings } from './gameSettings.js';
+export { ForcedOrientation, DisplayWinOdds } from './gameSettings.js';
+export type { ITokenData } from './tokenData.js';
+export type { IGameState } from './gameState.js';
+export type { IGameRoundInfo } from './gameRoundInfo.js';
+export type { IFreePlayInfo } from './freePlayInfo.js';
+export type { TPlayerChoiceFeatureAward, TPlayerChoiceCashAward, TPlayerChoiceAward } from './spinAward.js';
+export { isCashChoice, isFeatureChoice } from './spinAward.js';
+export type { ISpinInfo } from './spinInfo.js';
+export type { IScenarioInfo } from './scenarioInfo.js';
+export type { IGameResult } from './gameResult.js';
+export type { IBuyFeatureOption } from './buyFeatureOption.js';
+export type { ILoadConfigConfig } from './loadConfigConfig.js';
+export type { IProgressionCounterConfig, IProgressionEvent, TRandomChoiceAward, TRandomChoiceFeatureAward, TRandomChoiceCashAward, TProgressionAwarded } from './progressionCounter.js';
+export type { IConnectReply, ILoadConfigReply, IPlaceBetReply, ICollectReply, IRngDataEntry, IPfVerifyReply } from './replies.js';
+export type { ISessionOptions } from './sessionOptions.js';
+export type { ILoginOptions } from './loginOptions.js';
+export type { IPlaceBetOptions } from './placeBetOptions.js';
+export type { ICollectOptions } from './collectOptions.js';
+export type { IPfVerifyOptions, IPfVerifyAction } from './pfVerifyOptions.js';
+export type { TRouletteBetType, TRouletteBetSelection, TRouletteEvenMoneyBetType, IRouletteBet, IRouletteBetSettlement, IRouletteScenario, } from './roulette.js';
+export { rouletteAdditionalData } from './roulette.js';
+export type { TBlackjackRank, TBlackjackSuit, IBlackjackCard, TBlackjackAction, TBlackjackActionKind, IBlackjackSideBets, IBlackjackInitialBet, IBlackjackChoice, IBlackjackHand, IBlackjackDealer, IBlackjackPerfectPairsBet, IBlackjackTwentyOnePlusThreeBet, IBlackjackInsuranceBet, IBlackjackScenario, } from './blackjack.js';
+export { blackjackInitialData, blackjackActionData } from './blackjack.js';
+export type { ICrashBetRequest, ICrashBet, ICrashScenario, ICrashLoadConfig, TCrashEventName, ICrashRoundStartedPayload, ICrashRoundTickPayload, ICrashBetCashedOutPayload, ICrashRoundEndedPayload, ICrashBalanceUpdatedPayload, TCrashEvent, } from './crash.js';
+export { CRASH_EVENTS, crashPlaceBetData, crashCollectData } from './crash.js';
+export type { TMinesTile, IMinesScenario, } from './mines.js';
+export { minesPickData } from './mines.js';
+export type { IKenoScenario } from './keno.js';
+export { kenoPickData } from './keno.js';

package/lib/types/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kenoPickData = exports.minesPickData = exports.crashCollectData = exports.crashPlaceBetData = exports.CRASH_EVENTS = exports.blackjackActionData = exports.blackjackInitialData = exports.rouletteAdditionalData = exports.isFeatureChoice = exports.isCashChoice = exports.DisplayWinOdds = exports.ForcedOrientation = void 0;
+var gameSettings_js_1 = require("./gameSettings.js");
+Object.defineProperty(exports, "ForcedOrientation", { enumerable: true, get: function () { return gameSettings_js_1.ForcedOrientation; } });
+Object.defineProperty(exports, "DisplayWinOdds", { enumerable: true, get: function () { return gameSettings_js_1.DisplayWinOdds; } });
+var spinAward_js_1 = require("./spinAward.js");
+Object.defineProperty(exports, "isCashChoice", { enumerable: true, get: function () { return spinAward_js_1.isCashChoice; } });
+Object.defineProperty(exports, "isFeatureChoice", { enumerable: true, get: function () { return spinAward_js_1.isFeatureChoice; } });
+var roulette_js_1 = require("./roulette.js");
+Object.defineProperty(exports, "rouletteAdditionalData", { enumerable: true, get: function () { return roulette_js_1.rouletteAdditionalData; } });
+var blackjack_js_1 = require("./blackjack.js");
+Object.defineProperty(exports, "blackjackInitialData", { enumerable: true, get: function () { return blackjack_js_1.blackjackInitialData; } });
+Object.defineProperty(exports, "blackjackActionData", { enumerable: true, get: function () { return blackjack_js_1.blackjackActionData; } });
+var crash_js_1 = require("./crash.js");
+Object.defineProperty(exports, "CRASH_EVENTS", { enumerable: true, get: function () { return crash_js_1.CRASH_EVENTS; } });
+Object.defineProperty(exports, "crashPlaceBetData", { enumerable: true, get: function () { return crash_js_1.crashPlaceBetData; } });
+Object.defineProperty(exports, "crashCollectData", { enumerable: true, get: function () { return crash_js_1.crashCollectData; } });
+var mines_js_1 = require("./mines.js");
+Object.defineProperty(exports, "minesPickData", { enumerable: true, get: function () { return mines_js_1.minesPickData; } });
+var keno_js_1 = require("./keno.js");
+Object.defineProperty(exports, "kenoPickData", { enumerable: true, get: function () { return keno_js_1.kenoPickData; } });

package/lib/types/keno.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Keno-specific payloads carried through `IPlaceBetOptions.additionalData`
+ * and returned in `IGameResult.scenario`.
+ *
+ * The player either picks numbers explicitly or lets the engine auto-pick.
+ */
+/** The scenario returned in `IGameResult.scenario` for keno rounds. */
+export interface IKenoScenario {
+    /** How many numbers the player picked for this round. */
+    picks: number;
+    /** Risk level for this round (e.g. `"low"`, `"medium"`, `"high"`). */
+    risk: string;
+    /** Player's chosen numbers (1-indexed). */
+    playerNumbers: number[];
+    /** Numbers drawn by the engine (1-indexed). */
+    drawnNumbers: number[];
+    /** Count of overlap between `playerNumbers` and `drawnNumbers`. */
+    matches: number;
+    /** Payout multiplier applied to the stake. */
+    multiplier: number;
+    /** Total size of the draw pool. */
+    gridSize: number;
+    /** How many numbers are drawn per round. */
+    drawCount: number;
+}
+/**
+ * Build a `placeBet` additionalData payload for a keno pick.
+ *
+ * @param playerNumbers Optional player-selected numbers (1-indexed).
+ *   Must match the picks count for the selected feature. Omit to let the engine auto-pick.
+ */
+export declare function kenoPickData(playerNumbers?: number[]): {
+    playerNumbers?: number[];
+};

package/lib/types/keno.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Keno-specific payloads carried through `IPlaceBetOptions.additionalData`
+ * and returned in `IGameResult.scenario`.
+ *
+ * The player either picks numbers explicitly or lets the engine auto-pick.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kenoPickData = kenoPickData;
+/**
+ * Build a `placeBet` additionalData payload for a keno pick.
+ *
+ * @param playerNumbers Optional player-selected numbers (1-indexed).
+ *   Must match the picks count for the selected feature. Omit to let the engine auto-pick.
+ */
+function kenoPickData(playerNumbers) {
+    return playerNumbers ? { playerNumbers } : {};
+}

package/lib/types/loadConfigConfig.d.ts

@@ -0,0 +1,42 @@
+import type { IBuyFeatureOption } from './buyFeatureOption.js';
+import type { IProgressionCounterConfig } from './progressionCounter.js';
+/**
+ * Game configuration returned by `loadConfig()`.
+ * Contains stakes, RTP, and available features for the game.
+ */
+export interface ILoadConfigConfig {
+    /** Unique game identifier. */
+    gameCode: string;
+    /** Game type (e.g. "blackjack", "crash", "keno", "mines", "roulette"). Omitted for default DB-driven slot/plinko games. */
+    gameType?: string;
+    /** Available stake amounts the player can choose from. */
+    stakes?: number[];
+    /** Minimum allowed stake (currency-multiplied units). Present when the game config sets it. */
+    minStake?: number;
+    /** Maximum allowed stake (currency-multiplied units). Present when the game config sets it. */
+    maxStake?: number;
+    /** Return-to-player percentage (e.g. 95.5 for 95.5% RTP). */
+    rtp: number;
+    /** Optional maximum payout cap. */
+    maxPayoutCap?: number;
+    /** Optional maximum win amount eligible for wagering. */
+    maxWagerableWin?: number;
+    /** Optional minimum win amount eligible for wagering. */
+    minWagerableWin?: number;
+    /** Engine version string. */
+    version: string;
+    /** Available buy-feature options (each with an added `id` field). */
+    buyFeatures?: (IBuyFeatureOption & {
+        id: string;
+    })[];
+    /** Available wager feature names (e.g. "color-red"). */
+    wagerFeatures?: string[];
+    /** Available wager-stake feature names for multi-step wager games (e.g. mines, frogger). */
+    wagerStakeFeatures?: string[];
+    /** Progression counter configurations for this game. */
+    progressionCounters?: IProgressionCounterConfig[];
+    /** Current progression counter values loaded from player data. */
+    progressionCounterValues?: Record<string, number>;
+    /** Additional game-specific fields from loadConfig.json. */
+    [key: string]: unknown;
+}

package/lib/types/loadConfigConfig.js

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

package/lib/types/loginOptions.d.ts

@@ -0,0 +1,7 @@
+/** Options for the {@link login} call. */
+export interface ILoginOptions {
+    /** The operator-provided login endpoint URL (from the launch URL query string). */
+    loginURL: string;
+    /** Short-lived launch token (from the launch URL query string). */
+    launchToken: string;
+}

package/lib/types/loginOptions.js

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

package/lib/types/mines.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Mines-specific payloads carried through `IPlaceBetOptions.additionalData`
+ * and returned in `IGameResult.scenario`.
+ *
+ * Mines is a multi-step wager game: the initial `placeBet` opens a round, and
+ * each subsequent `placeBet` reveals one tile. The round continues until the
+ * player hits a bomb or cashes out via `collect()`.
+ */
+export type TMinesTile = null | 'bomb' | 'picked';
+/** The scenario returned in `IGameResult.scenario` for mines rounds. */
+export interface IMinesScenario {
+    /** Board state: null = unknown, 'picked' = safe pick, 'bomb' = mine. */
+    board: TMinesTile[];
+    /** Current cumulative win multiplier. */
+    currentMultiplier: number;
+    /** Number of mines on the board. */
+    mineCount: number;
+}
+/**
+ * Build a `placeBet` additionalData payload for a mines tile pick.
+ *
+ * @param pickPosition Zero-based index of the tile to reveal.
+ */
+export declare function minesPickData(pickPosition: number): {
+    pickPosition: number;
+};

package/lib/types/mines.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Mines-specific payloads carried through `IPlaceBetOptions.additionalData`
+ * and returned in `IGameResult.scenario`.
+ *
+ * Mines is a multi-step wager game: the initial `placeBet` opens a round, and
+ * each subsequent `placeBet` reveals one tile. The round continues until the
+ * player hits a bomb or cashes out via `collect()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.minesPickData = minesPickData;
+/**
+ * Build a `placeBet` additionalData payload for a mines tile pick.
+ *
+ * @param pickPosition Zero-based index of the tile to reveal.
+ */
+function minesPickData(pickPosition) {
+    return { pickPosition };
+}

package/lib/types/network.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Discriminated union wrapping all SDK API responses.
+ * Check `success` before accessing `result` or `error`.
+ */
+export type TNetworkResponse<T> = TNetworkSuccess<T> | TNetworkError;
+/** Successful API response. Access the payload via `result`. */
+export type TNetworkSuccess<T> = {
+    success: true;
+    result: T;
+};
+/** Failed API response. Inspect `error` for the failure reason. */
+export type TNetworkError = {
+    success: false;
+    error: IErrorResponse;
+};
+/** Error details returned when an API call fails. */
+export interface IErrorResponse {
+    /** Machine-readable error code (stringified `API_RETURNCODES` value or engine-specific id). Prefers the `X-H-ERROR-ID` response header, falling back to the response body. */
+    code: string;
+    /** Human-readable error description. Prefers the `X-H-ERROR-MSG(-BASE64)` response header, falling back to the response body or HTTP status text. */
+    message: string;
+    /** Optional operator-specific data for custom error handling. */
+    passThroughData?: unknown;
+}

package/lib/types/network.js

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

package/lib/types/pfVerifyOptions.d.ts

@@ -0,0 +1,48 @@
+import type { ISessionOptions } from './sessionOptions.js';
+/**
+ * One replay action. Field used depends on the game type:
+ *
+ * - **blackjack** — `{ action: { kind: 'hit' | 'stand' | … } }`. Raw
+ *   `TRulesAction` object passed straight to the rules engine.
+ * - **mines** — `{ pickPosition: number }` for every step (including the
+ *   opening pick). `playerChoiceIndex` only when the engine surfaced a
+ *   mid-round choice.
+ * - **fixed-odds / slot / frogger / hi-lo / over-under / plinko** —
+ *   `{ playerChoiceIndex: number }` for each wager-feature / playerChoice
+ *   step. Initial spin needs no entry in `actions`.
+ *
+ * Other one-shot rounds (roulette / keno / crash) take no actions; the
+ * opening request fields are sufficient.
+ */
+export interface IPfVerifyAction {
+    /** Blackjack: raw `TRulesAction` (e.g. `{ kind: 'hit' }`). */
+    action?: Record<string, unknown>;
+    /** Fixed-odds / mines: index into the previous step's `engineData.playerChoice`. */
+    playerChoiceIndex?: number;
+    /** Mines: tile picked at this step. */
+    pickPosition?: number;
+}
+/** Options for the {@link pfVerify} call. */
+export interface IPfVerifyOptions extends ISessionOptions {
+    /** The revealed `serverSeed` from the round's `pf` block. */
+    serverSeed: string;
+    /** The `clientSeed` bound to that round. */
+    clientSeed: string;
+    /**
+     * Nonce at which the round's PF chain begins. Defaults to `0`. Set it
+     * only if the round opened mid-stream against an existing PF session.
+     */
+    startNonce?: number;
+    /** The stake the round opened with. Required by games that need it to settle (blackjack, fixed-odds wager). */
+    stake?: number;
+    /** Buy-feature id the round opened on, if any (mines mine-count, slot bonus buy, …). */
+    featureToBuy?: string;
+    /** Mirror the round's opening payload — currently blackjack `{ sideBets }`. */
+    initialData?: Record<string, unknown>;
+    /** Roulette `IRouletteBet[]` or crash `ICrashBet[]` — the round's opening bets. */
+    bets?: unknown[];
+    /** Keno: the player numbers, if the round was opened with explicit picks. */
+    playerNumbers?: number[];
+    /** Continuation actions in order. Shape per game — see {@link IPfVerifyAction}. */
+    actions?: IPfVerifyAction[];
+}

package/lib/types/pfVerifyOptions.js

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

package/lib/types/placeBetOptions.d.ts

@@ -0,0 +1,16 @@
+import type { ISessionOptions } from './sessionOptions.js';
+/** Options for the {@link placeBet} call. */
+export interface IPlaceBetOptions extends ISessionOptions {
+    /** Stake amount in minor currency units. Required for the first call of a game round. */
+    stake?: number;
+    /** Set `true` to consume a free play ticket instead of deducting from balance. */
+    useTicket?: boolean;
+    /** Feature type of the free play ticket being consumed. */
+    useTicketFeatureType?: string;
+    /** Buy-feature ID to purchase (e.g. `'freespin'`). See `config.buyFeatures`. */
+    featureToBuy?: string;
+    /** Index of the selected option when `engineData.playerChoice` is set. */
+    playerChoiceIndex?: number;
+    /** Additional game-specific parameters. */
+    additionalData?: Record<string, unknown>;
+}

package/lib/types/placeBetOptions.js

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

package/lib/types/progressionCounter.d.ts

@@ -0,0 +1,65 @@
+import type { TPlayerChoiceAward, TPlayerChoiceCashAward, TPlayerChoiceFeatureAward } from './spinAward.js';
+/** Feature award with optional weighting for random selection. */
+export type TRandomChoiceFeatureAward = TPlayerChoiceFeatureAward & {
+    weighting?: number;
+};
+/** Cash award with optional weighting for random selection. */
+export type TRandomChoiceCashAward = TPlayerChoiceCashAward & {
+    weighting?: number;
+};
+/**
+ * A single option in a counter's `randomChoice` `onComplete.awards` array.
+ * Independently either a feature-spin award or a cash award.
+ */
+export type TRandomChoiceAward = TRandomChoiceFeatureAward | TRandomChoiceCashAward;
+/**
+ * Counter completion configuration — selection mode (`playerChoice` or
+ * `randomChoice`) is at the top level; each individual award option is
+ * independently a feature-spin award or a cash award. The two kinds may
+ * be mixed freely in the same array.
+ */
+export type TProgressionAwarded = {
+    type: 'playerChoice';
+    awards: TPlayerChoiceAward[];
+} | {
+    type: 'randomChoice';
+    awards: TRandomChoiceAward[];
+};
+/** Configuration for a single progression counter defined at the game config level. */
+export interface IProgressionCounterConfig {
+    /** Counter name — matches keys in entry `progressionAwards`. */
+    name: string;
+    /** Award granted when the counter reaches 1.0. Each option in the awards array is independently a feature spin or cash payout. */
+    onComplete: TProgressionAwarded;
+    /** If true, maintain a separate counter per stake level. */
+    stakeSpecific: boolean;
+}
+/**
+ * Per-scenario progression counter event emitted on a `placeBet` response.
+ * One entry per counter that had activity during the current scenario step —
+ * either an increment, a threshold crossing, or both. The frontend reads
+ * these to animate the counter change and the prize award at the moment
+ * they happen, instead of seeing only the entry's end-of-round state.
+ *
+ *  - `delta` / `value`: the increment applied and the counter's value
+ *    after this step (post any threshold reset).
+ *  - `cashWin` / `featureAwards` / `playerChoiceRequested`: present when
+ *    the increment crossed `1.0` and `onComplete` fired. Multiple awards
+ *    on the same step (delta ≥ 1.0, or a `playerChoice` plus a cash
+ *    resolution from a later iteration) aggregate into a single event.
+ *    `playerChoice` resolutions also surface as `engineData.playerChoice`.
+ */
+export interface IProgressionEvent {
+    /** Counter name (matches an entry in `progressionCounters`). */
+    counter: string;
+    /** Increment applied this step. */
+    delta: number;
+    /** Counter value after this step's delta and any threshold reset. */
+    value: number;
+    /** Total cash awarded by `randomChoice` resolutions on this step, in stake-multiplier units. */
+    cashWin?: number;
+    /** Feature awards merged into `spinInfo` by `randomChoice` resolutions on this step. */
+    featureAwards?: TRandomChoiceFeatureAward[];
+    /** Set when a threshold crossing on this step required player input. */
+    playerChoiceRequested?: boolean;
+}

package/lib/types/progressionCounter.js

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