@smartico/public-api 0.0.409 → 0.0.411

package/docs/api/interfaces/TMiniGamePrize.md

@@ -16,7 +16,7 @@ ID of the prize
 
 > **name**: `string`
 
-The visual name of the prize
+Display name of the prize, pre-translated; any jackpot placeholder in it arrives resolved to the live jackpot value
 
 ***
 
@@ -24,7 +24,7 @@ The visual name of the prize
 
 > **prize\_type**: [`MiniGamePrizeTypeName`](../enumerations/MiniGamePrizeTypeName.md)
 
-The type of the prize,  no-prize, points, bonus, manual, spin, jackpot
+The type of the prize — see [MiniGamePrizeTypeName](../enumerations/MiniGamePrizeTypeName.md) ('no-prize', 'points', 'gems-and-diamonds', 'spin', 'bonus', 'jackpot', 'raffle-ticket', 'mission', 'change-level', 'manual')
 
 ***
 
@@ -32,7 +32,7 @@ The type of the prize,  no-prize, points, bonus, manual, spin, jackpot
 
 > `optional` **prize\_value?**: `number`
 
-Numeric value of the prize in case it's 'points' or 'spin' type. For other types of prizes this value is not relevant. 
+Numeric value of the prize in case it's 'points' or 'spin' type. For other types of prizes this value is not relevant.
 For example for prize  '100 points' the prize_value will be 100. For '100 free spins' the prize_value will be 100.
 
 ***
@@ -41,7 +41,7 @@ For example for prize  '100 points' the prize_value will be 100. For '100 free s
 
 > `optional` **font\_size?**: `number`
 
-Custom font size for the prize (desktop)
+Custom font size in px for rendering the prize name on the game surface (e.g. a wheel sector), desktop
 
 ***
 
@@ -49,7 +49,7 @@ Custom font size for the prize (desktop)
 
 > `optional` **font\_size\_mobile?**: `number`
 
-Custom font size for the prize (mobile)
+Custom font size in px for the prize name, mobile; falls back to `font_size` when absent
 
 ***
 
@@ -65,7 +65,7 @@ The URL of the icon of the prize, aspect ratio 1:1
 
 > **position**: `number`
 
-for scratch card defines position of prize in the list
+For Scratch Card games — relative order of the prize in the scratch grid (lower first). May be absent for other game types
 
 ***
 
@@ -73,7 +73,7 @@ for scratch card defines position of prize in the list
 
 > **sectors**: `number`[]
 
-List of sectors for the prize
+For Spin-a-Wheel games — wheel sector indices this prize occupies. Absent for non-wheel games
 
 ***
 
@@ -81,7 +81,7 @@ List of sectors for the prize
 
 > **acknowledge\_type**: [`SAWAcknowledgeTypeName`](../enumerations/SAWAcknowledgeTypeName.md)
 
-Type of acknowledge message for users
+Which win modal the prize uses — see [SAWAcknowledgeTypeName](../enumerations/SAWAcknowledgeTypeName.md) (Silent / QuickMessage / FullMessage / ExplicitAcknowledge)
 
 ***
 
@@ -93,11 +93,19 @@ Message that will be shown to user in modal pop-up
 
 ***
 
+### aknowledge\_message\_lose?
+
+> `optional` **aknowledge\_message\_lose?**: `string`
+
+Message shown instead of `aknowledge_message` when the spin is finalised as lost (`lose: true` acknowledge flows — games with a client-decided outcome, e.g. Voyager). Absent unless configured
+
+***
+
 ### acknowledge\_dp
 
 > **acknowledge\_dp**: `string`
 
-Deep link that will trigger some action in modal pop-up
+Deep link executed when the user taps the main action button in the win modal (run it via `_smartico.dp()`)
 
 ***
 
@@ -105,7 +113,7 @@ Deep link that will trigger some action in modal pop-up
 
 > **acknowledge\_action\_title**: `string`
 
-The name of the action button in modal pop-up
+Label of the main action button in the win modal
 
 ***
 
@@ -113,7 +121,7 @@ The name of the action button in modal pop-up
 
 > `optional` **acknowledge\_dp\_additional?**: `string`
 
-Deep link that will trigger some action in modal pop-up (additional)
+Deep link of the additional action button in the win modal
 
 ***
 
@@ -121,7 +129,23 @@ Deep link that will trigger some action in modal pop-up (additional)
 
 > `optional` **acknowledge\_action\_title\_additional?**: `string`
 
-The name of the action button in modal pop-up (additional)
+Label of the additional action button in the win modal
+
+***
+
+### second\_btn?
+
+> `optional` **second\_btn?**: `string`
+
+Deep link of the secondary button in the win modal
+
+***
+
+### second\_btn\_action\_title?
+
+> `optional` **second\_btn\_action\_title?**: `string`
+
+Label of the secondary button in the win modal
 
 ***
 
@@ -137,7 +161,7 @@ Message when the prize pool is empty for that specific prize
 
 > `optional` **pool?**: `number`
 
-Number of items in stock
+Remaining stock of the prize — decrements on each win, refunded if the spin is finalised as lost. Populated only when the template's `expose_game_stat_on_api` is enabled; always populated for MatchX / Quiz games
 
 ***
 
@@ -145,7 +169,7 @@ Number of items in stock
 
 > `optional` **pool\_initial?**: `number`
 
-Initial number of items in stock
+Initial (configured) stock of the prize. Populated regardless of `expose_game_stat_on_api`
 
 ***
 
@@ -153,7 +177,7 @@ Initial number of items in stock
 
 > `optional` **wins\_count?**: `number`
 
-Number of wins in game
+Number of times the prize has been won, across all players. Populated only when the template's `expose_game_stat_on_api` is enabled
 
 ***
 
@@ -161,7 +185,7 @@ Number of wins in game
 
 > `optional` **weekdays?**: `number`[]
 
-Number of days of week, when the prize can be available
+ISO weekday numbers (1 = Monday … 7 = Sunday) on which the prize can be won; absent = any day. Populated only when the template's `expose_game_stat_on_api` is enabled
 
 ***
 
@@ -169,7 +193,7 @@ Number of days of week, when the prize can be available
 
 > `optional` **active\_from\_ts?**: `number`
 
-Holds time from which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp)
+Time from which the prize can be won (epoch ms), evaluated against `relative_period_timezone`. Populated only when the template's `expose_game_stat_on_api` is enabled
 
 ***
 
@@ -177,7 +201,7 @@ Holds time from which prize will become available, for the prizes that are targe
 
 > `optional` **active\_till\_ts?**: `number`
 
-Holds time till which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp)
+Time until which the prize can be won (epoch ms), evaluated against `relative_period_timezone`. Populated only when the template's `expose_game_stat_on_api` is enabled
 
 ***
 
@@ -185,7 +209,7 @@ Holds time till which prize will become available, for the prizes that are targe
 
 > `optional` **relative\_period\_timezone?**: `number`
 
-Time zone to ensure each day aligns with your local midnight.
+Timezone offset in minutes used to evaluate `weekdays` and the active window (UTC minus local, as in JS `Date.getTimezoneOffset()` — e.g. `-180` for UTC+3)
 
 ***
 
@@ -193,7 +217,7 @@ Time zone to ensure each day aligns with your local midnight.
 
 > `optional` **is\_surcharge?**: `boolean`
 
-Flag indicating that the prize is surcharged (available all the time, despite pool numbers)
+When true, the prize stays winnable even when its `pool` reaches 0 (effectively unlimited stock)
 
 ***
 
@@ -201,7 +225,7 @@ Flag indicating that the prize is surcharged (available all the time, despite po
 
 > `optional` **is\_deleted?**: `boolean`
 
-Flag indicating the state of the prize
+Always `false` in API responses — deleted prizes are excluded server-side
 
 ***
 
@@ -209,7 +233,7 @@ Flag indicating the state of the prize
 
 > `optional` **custom\_data?**: `any`
 
-The custom data of the mini-game defined by operator in the BackOffice. Can be a JSON object, string or number
+The custom data of the prize defined by the operator. Can be a JSON object, string or number
 
 ***
 
@@ -217,7 +241,7 @@ The custom data of the mini-game defined by operator in the BackOffice. Can be a
 
 > `optional` **prize\_modifiers?**: [`PrizeModifiers`](../enumerations/PrizeModifiers.md)[]
 
-Prize modifiers that will multiply by 2x, 5x or 10x the current total. This will not affect the final Prize Amount that will be awarded.
+Step-modifier tiles for step games (Treasure Hunt / Voyager) — see [PrizeModifiers](../enumerations/PrizeModifiers.md) (2x / 5x / 10x, /2 / /5 / /10, 0, reset) applied to the running total revealed during the game. Presentation only — the awarded amount is still `prize_value`
 
 ***
 
@@ -225,7 +249,7 @@ Prize modifiers that will multiply by 2x, 5x or 10x the current total. This will
 
 > `optional` **allow\_split\_decimal?**: `boolean`
 
-When enabled, you can split prize value by decimal values
+Step games (Treasure Hunt / Voyager): when true, the per-step revealed amounts of the prize value may be fractional; when false the split uses whole numbers
 
 ***
 
@@ -233,7 +257,7 @@ When enabled, you can split prize value by decimal values
 
 > `optional` **hide\_prize\_from\_history?**: `boolean`
 
-When enabled, you can hide prize from prize history
+Operator hint to hide this prize when rendering prize-history UIs. Informational only — API responses are not filtered by it
 
 ***
 
@@ -241,7 +265,7 @@ When enabled, you can hide prize from prize history
 
 > `optional` **requirements\_to\_get\_prize?**: `string`
 
-Requirements to claim the prize  (lootbox specific)
+Operator text describing what the user must do to be eligible for this prize (lootbox games); shown when the prize is not yet available to the user
 
 ***
 
@@ -249,4 +273,4 @@ Requirements to claim the prize  (lootbox specific)
 
 > `optional` **max\_give\_period\_type\_id?**: [`AttemptPeriodType`](../enumerations/AttemptPeriodType.md)
 
-The period type for the prize to be given: Time from last attempt, Calendar days UTC, Calendar days user time zone, Lifetime
+Period basis for the prize availability restriction — see [AttemptPeriodType](../enumerations/AttemptPeriodType.md). `CalendarDaysUserTimeZone` evaluates `weekdays` / the active window in the user's timezone; the other types use `relative_period_timezone`

package/docs/api/interfaces/TMiniGameTemplate.md

@@ -96,10 +96,9 @@ in case of charging type 'Spin attempts', shows the current number of spin attem
 
 > **next\_available\_spin\_ts**: `number`
 
-if the game is limit to the number of spins that user can do during period of time,
-this property shows the epoch time in UTC when the next attempt will be available.
-Note that you need to enable 'Show time to the next available spin' setting on mini-game template in the backoffice
-Important: this field will not be populated if “Max number of attempts a user can do” is set to value different from 1
+If the game limits the number of attempts per period of time, the epoch-ms time (UTC) when the next attempt becomes available.
+Populated only when the operator enabled the "show time to the next available spin" template setting, and only when the
+template's maximum attempts per period is 1.
 
 ***
 
@@ -144,7 +143,7 @@ The message that should be shown to the user when he cannot play the game becaus
 
 > **jackpot\_current**: `number`
 
-Current jackpont amount, if jackpot is enabled.
+Current jackpot amount, if jackpot is enabled.
 
 ***
 
@@ -192,7 +191,7 @@ The custom data of the mini-game defined by operator in the BackOffice. Can be a
 
 > **prizes**: [`TMiniGamePrize`](TMiniGamePrize.md)[]
 
-List of prizes for mini-games
+Prizes configured for this game — see [TMiniGamePrize](TMiniGamePrize.md)
 
 ***
 
@@ -200,7 +199,7 @@ List of prizes for mini-games
 
 > `optional` **expose\_game\_stat\_on\_api?**: `boolean`
 
-When enabled, the number of items in the pool and number of won items will be exposed in the Retention API and in the UI Widgets
+Operator template setting. When enabled, the per-prize stock statistics (`pool`, `wins_count`, `weekdays`, `active_from_ts` / `active_till_ts`) are populated on `prizes` and kept current after every play; when disabled (default) those fields are omitted. See `getMiniGames` "Per-prize statistics"
 
 ***
 
@@ -208,7 +207,7 @@ When enabled, the number of items in the pool and number of won items will be ex
 
 > `optional` **relative\_period\_timezone?**: `number`
 
-Time zone to ensure each day aligns with your local midnight.
+Timezone offset in minutes used to evaluate the template's period-based rules (UTC minus local, as in JS `Date.getTimezoneOffset()` — e.g. `-180` for UTC+3)
 
 ***
 
@@ -216,7 +215,7 @@ Time zone to ensure each day aligns with your local midnight.
 
 > `optional` **activeFromDate?**: `number`
 
-Holds time from which template will become available, for the template that are targeted to be available from specific time (UNIX timestamp)
+Time from which the template becomes available (epoch ms); absent when not restricted
 
 ***
 
@@ -224,7 +223,7 @@ Holds time from which template will become available, for the template that are
 
 > `optional` **activeTillDate?**: `number`
 
-Holds time till which template will become available, for the templates that are targeted to be available from specific time (UNIX timestamp)
+Time until which the template stays available (epoch ms); absent when not restricted
 
 ***
 
@@ -232,7 +231,7 @@ Holds time till which template will become available, for the templates that are
 
 > `optional` **steps\_to\_finish\_game?**: `number`
 
-The amount of steps to complete the game and gather the prize
+Number of steps to complete the game and collect the prize (step games — Voyager / Treasure Hunt)
 
 ***
 
@@ -240,7 +239,7 @@ The amount of steps to complete the game and gather the prize
 
 > `optional` **custom\_section\_id?**: `number`
 
-Hold the id of the custom section
+ID of the operator-defined custom section (widget menu grouping) the mini-game is assigned to
 
 ***
 
@@ -248,7 +247,7 @@ Hold the id of the custom section
 
 > **saw\_template\_ui\_definition**: [`SAWTemplateUI`](SAWTemplateUI.md)
 
-The UI definition of the mini-game
+Full raw UI definition of the mini-game (skin, colors, per-game visual settings) — see [SAWTemplateUI](SAWTemplateUI.md). The commonly needed values are already lifted onto this template object
 
 ***
 
@@ -256,7 +255,7 @@ The UI definition of the mini-game
 
 > `optional` **game\_layout?**: [`SAWGameLayoutName`](../enumerations/SAWGameLayoutName.md)
 
-The layout of the game
+Grid layout of the game. Populated only for Lootbox game types (LootboxWeekdays / LootboxCalendarDays)
 
 ***
 
@@ -264,7 +263,7 @@ The layout of the game
 
 > `optional` **show\_prize\_history?**: `boolean`
 
-When enabled the prize history icon is visible on a certain template
+Operator setting: show a prize-history entry point (icon / button) on this game's view
 
 ***
 
@@ -288,4 +287,4 @@ The period of time in milliseconds during which the user can do the maximum numb
 
 > `optional` **expose\_user\_spin\_id?**: [`SAWExposeUserSpinIdName`](../enumerations/SAWExposeUserSpinIdName.md)
 
-The ID of the user spin id to expose on the game
+Which identifier to show next to a win result for transparency/audit — 'userId' (the player's external user id) or 'spinId' (the spin's transaction id). Absent when the operator disabled it

package/docs/capabilities/getJackpotEligibleGames.md

@@ -33,7 +33,7 @@ _None._
 
 ## Behavioral contract
 **Preconditions**
-- User must be authenticated. Visitor mode not supported.
+- No authentication required — works in both identified and visitor mode.
 - `jp_template_id` is mandatory.
 
 **`onUpdate` caveat**
@@ -51,7 +51,12 @@ Treat it as a no-op for now.
 Non-zero `errCode` on control-group users or generic server errors.
 Branch on `errCode === 0` and surface `errMsg` on failure.
 
-**Visitor mode**: not supported.
+**Visitor mode**: supported via
+`_smartico.vapi(lang).getJackpotEligibleGames(...)`. The eligible-games
+list is template-level (which games contribute to the pot) and carries no
+per-user fields, so a visitor session receives the same list an identified
+user would. The `lang` passed to `_smartico.vapi(lang)` drives the
+translation of game names.
 
 **UI guidance**: see [UI Guide — `getJackpotEligibleGames`](../../docs/ui/jackpots/UIGuide_getJackpotEligibleGames.md).
 
@@ -66,6 +71,10 @@ if (jp?.ach_related_game_allow_all) {
 
 const r = await window._smartico.api.getJackpotEligibleGames({ jp_template_id: 42 });
 console.log('[smartico] render', r.eligible_games.length, 'eligible game tiles');
+
+// Visitor mode — same shape, language driven by the vapi(lang) argument
+const visitor = await window._smartico.vapi('EN').getJackpotEligibleGames({ jp_template_id: 42 });
+console.log('[smartico] visitor eligible games:', visitor.eligible_games.length);
 ```
 
 ### Example response (REAL shape)

package/docs/capabilities/getMiniGames.md

@@ -30,56 +30,59 @@ Array of `TMiniGameTemplate`. Each item:
 - `buyin_cost_gems` (number) — in case of charging type 'Gems', what is the gems amount will be deducted from user balance
 - `buyin_cost_diamonds` (number) — in case of charging type 'Diamonds', what is the diamonds amount will be deducted from user balance
 - `spin_count` (number) — in case of charging type 'Spin attempts', shows the current number of spin attempts that user has
-- `next_available_spin_ts` (number) — if the game is limit to the number of spins that user can do during period of time, this property shows the epoch time in UTC when the next attempt will be available. Note that you need to enable 'Show time to the next available spin' setting on mini-game template in the backoffice Important: this field will not be populated if “Max number of attempts a user can do” is set to value different from 1
+- `next_available_spin_ts` (number) — If the game limits the number of attempts per period of time, the epoch-ms time (UTC) when the next attempt becomes available. Populated only when the operator enabled the "show time to the next available spin" template setting, and only when the template's maximum attempts per period is 1.
 - `earliest_expiration_dt` (number | null) — Soonest-expiring spin's expiration time for the current user, as an epoch-ms timestamp. `null` when the user has no expirable spins for this template — spins only expire when the template defines a spin-expiration rule (Wheel of Fortune, Loot Boxes, etc.). Pair with `latest_expiration_dt` to render a "spins expire between X and Y" window.
 - `latest_expiration_dt` (number | null) — Latest-expiring spin's expiration time for the current user, as an epoch-ms timestamp. `null` when the user has no expirable spins; equals `earliest_expiration_dt` when a single expiration applies.
 - `over_limit_message` (string) — The message that should be shown to the user when he cannot play the game, server rejected attempt with error code SAWSpinErrorCode.SAW_FAILED_MAX_SPINS_REACHED
 - `no_attempts_message` (string) — The message that should be shown to the user when he cannot play the game because he doesn't have spin attempts or points.
-- `jackpot_current` (number) — Current jackpont amount, if jackpot is enabled.
+- `jackpot_current` (number) — Current jackpot amount, if jackpot is enabled.
 - `jackpot_add_on_attempt` (number) — The amount that will be added to the jackpot every time when somebody plays the game. Note that the contribution amount is abstract, means that no money or points are deducted from the user balance.
 - `jackpot_symbol` (string) — The symbol of jackpot that is giving the sense to the 'amount' E.g. the symbol could be EUR and connected to the amount it can indicate that amount is monetary, e.g. '100 EUR'. Or the symbol can be 'Free spins' and connected to the amount it can indicate that amount is number of free spins, e.g. '100 Free spins'.
 - `promo_image` (string) — The promo image, 500x240px
 - `promo_text` (string) — The promo text
 - `custom_data` (any) — The custom data of the mini-game defined by operator in the BackOffice. Can be a JSON object, string or number
-- `prizes` (TMiniGamePrize[]) — List of prizes for mini-games
+- `prizes` (TMiniGamePrize[]) — Prizes configured for this game — see `TMiniGamePrize`
   - `id` (number) — ID of the prize
-  - `name` (string) — The visual name of the prize
-  - `prize_type` (MiniGamePrizeTypeName) — The type of the prize, no-prize, points, bonus, manual, spin, jackpot
+  - `name` (string) — Display name of the prize, pre-translated; any jackpot placeholder in it arrives resolved to the live jackpot value
+  - `prize_type` (MiniGamePrizeTypeName) — The type of the prize — see `MiniGamePrizeTypeName` ('no-prize', 'points', 'gems-and-diamonds', 'spin', 'bonus', 'jackpot', 'raffle-ticket', 'mission', 'change-level', 'manual')
   - `prize_value` (number) — Numeric value of the prize in case it's 'points' or 'spin' type. For other types of prizes this value is not relevant. For example for prize '100 points' the prize_value will be 100. For '100 free spins' the prize_value will be 100.
-  - `font_size` (number) — Custom font size for the prize (desktop)
-  - `font_size_mobile` (number) — Custom font size for the prize (mobile)
+  - `font_size` (number) — Custom font size in px for rendering the prize name on the game surface (e.g. a wheel sector), desktop
+  - `font_size_mobile` (number) — Custom font size in px for the prize name, mobile; falls back to `font_size` when absent
   - `icon` (string) — The URL of the icon of the prize, aspect ratio 1:1
-  - `position` (number) — for scratch card defines position of prize in the list
-  - `sectors` (number[]) — List of sectors for the prize
-  - `acknowledge_type` (SAWAcknowledgeTypeName) — Type of acknowledge message for users
+  - `position` (number) — For Scratch Card games — relative order of the prize in the scratch grid (lower first). May be absent for other game types
+  - `sectors` (number[]) — For Spin-a-Wheel games — wheel sector indices this prize occupies. Absent for non-wheel games
+  - `acknowledge_type` (SAWAcknowledgeTypeName) — Which win modal the prize uses — see `SAWAcknowledgeTypeName` (Silent / QuickMessage / FullMessage / ExplicitAcknowledge)
   - `aknowledge_message` (string) — Message that will be shown to user in modal pop-up
-  - `acknowledge_dp` (string) — Deep link that will trigger some action in modal pop-up
-  - `acknowledge_action_title` (string) — The name of the action button in modal pop-up
-  - `acknowledge_dp_additional` (string) — Deep link that will trigger some action in modal pop-up (additional)
-  - `acknowledge_action_title_additional` (string) — The name of the action button in modal pop-up (additional)
+  - `aknowledge_message_lose` (string) — Message shown instead of `aknowledge_message` when the spin is finalised as lost (`lose: true` acknowledge flows — games with a client-decided outcome, e.g. Voyager). Absent unless configured
+  - `acknowledge_dp` (string) — Deep link executed when the user taps the main action button in the win modal (run it via `_smartico.dp()`)
+  - `acknowledge_action_title` (string) — Label of the main action button in the win modal
+  - `acknowledge_dp_additional` (string) — Deep link of the additional action button in the win modal
+  - `acknowledge_action_title_additional` (string) — Label of the additional action button in the win modal
+  - `second_btn` (string) — Deep link of the secondary button in the win modal
+  - `second_btn_action_title` (string) — Label of the secondary button in the win modal
   - `out_of_stock_message` (string) — Message when the prize pool is empty for that specific prize
-  - `pool` (number) — Number of items in stock
-  - `pool_initial` (number) — Initial number of items in stock
-  - `wins_count` (number) — Number of wins in game
-  - `weekdays` (number[]) — Number of days of week, when the prize can be available
-  - `active_from_ts` (number) — Holds time from which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp)
-  - `active_till_ts` (number) — Holds time till which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp)
-  - `relative_period_timezone` (number) — Time zone to ensure each day aligns with your local midnight.
-  - `is_surcharge` (boolean) — Flag indicating that the prize is surcharged (available all the time, despite pool numbers)
-  - `is_deleted` (boolean) — Flag indicating the state of the prize
-  - `custom_data` (any) — The custom data of the mini-game defined by operator in the BackOffice. Can be a JSON object, string or number
-  - `prize_modifiers` (PrizeModifiers[]) — Prize modifiers that will multiply by 2x, 5x or 10x the current total. This will not affect the final Prize Amount that will be awarded.
-  - `allow_split_decimal` (boolean) — When enabled, you can split prize value by decimal values
-  - `hide_prize_from_history` (boolean) — When enabled, you can hide prize from prize history
-  - `requirements_to_get_prize` (string) — Requirements to claim the prize (lootbox specific)
-  - `max_give_period_type_id` (AttemptPeriodType) — The period type for the prize to be given: Time from last attempt, Calendar days UTC, Calendar days user time zone, Lifetime
-- `expose_game_stat_on_api` (boolean) — When enabled, the number of items in the pool and number of won items will be exposed in the Retention API and in the UI Widgets
-- `relative_period_timezone` (number) — Time zone to ensure each day aligns with your local midnight.
-- `activeFromDate` (number) — Holds time from which template will become available, for the template that are targeted to be available from specific time (UNIX timestamp)
-- `activeTillDate` (number) — Holds time till which template will become available, for the templates that are targeted to be available from specific time (UNIX timestamp)
-- `steps_to_finish_game` (number) — The amount of steps to complete the game and gather the prize
-- `custom_section_id` (number) — Hold the id of the custom section
-- `saw_template_ui_definition` (SAWTemplateUI) — The UI definition of the mini-game
+  - `pool` (number) — Remaining stock of the prize — decrements on each win, refunded if the spin is finalised as lost. Populated only when the template's `expose_game_stat_on_api` is enabled; always populated for MatchX / Quiz games
+  - `pool_initial` (number) — Initial (configured) stock of the prize. Populated regardless of `expose_game_stat_on_api`
+  - `wins_count` (number) — Number of times the prize has been won, across all players. Populated only when the template's `expose_game_stat_on_api` is enabled
+  - `weekdays` (number[]) — ISO weekday numbers (1 = Monday … 7 = Sunday) on which the prize can be won; absent = any day. Populated only when the template's `expose_game_stat_on_api` is enabled
+  - `active_from_ts` (number) — Time from which the prize can be won (epoch ms), evaluated against `relative_period_timezone`. Populated only when the template's `expose_game_stat_on_api` is enabled
+  - `active_till_ts` (number) — Time until which the prize can be won (epoch ms), evaluated against `relative_period_timezone`. Populated only when the template's `expose_game_stat_on_api` is enabled
+  - `relative_period_timezone` (number) — Timezone offset in minutes used to evaluate `weekdays` and the active window (UTC minus local, as in JS `Date.getTimezoneOffset()` — e.g. `-180` for UTC+3)
+  - `is_surcharge` (boolean) — When true, the prize stays winnable even when its `pool` reaches 0 (effectively unlimited stock)
+  - `is_deleted` (boolean) — Always `false` in API responses — deleted prizes are excluded server-side
+  - `custom_data` (any) — The custom data of the prize defined by the operator. Can be a JSON object, string or number
+  - `prize_modifiers` (PrizeModifiers[]) — Step-modifier tiles for step games (Treasure Hunt / Voyager) — see `PrizeModifiers` (2x / 5x / 10x, /2 / /5 / /10, 0, reset) applied to the running total revealed during the game. Presentation only — the awarded amount is still `prize_value`
+  - `allow_split_decimal` (boolean) — Step games (Treasure Hunt / Voyager): when true, the per-step revealed amounts of the prize value may be fractional; when false the split uses whole numbers
+  - `hide_prize_from_history` (boolean) — Operator hint to hide this prize when rendering prize-history UIs. Informational only — API responses are not filtered by it
+  - `requirements_to_get_prize` (string) — Operator text describing what the user must do to be eligible for this prize (lootbox games); shown when the prize is not yet available to the user
+  - `max_give_period_type_id` (AttemptPeriodType) — Period basis for the prize availability restriction — see `AttemptPeriodType`. `CalendarDaysUserTimeZone` evaluates `weekdays` / the active window in the user's timezone; the other types use `relative_period_timezone`
+- `expose_game_stat_on_api` (boolean) — Operator template setting. When enabled, the per-prize stock statistics (`pool`, `wins_count`, `weekdays`, `active_from_ts` / `active_till_ts`) are populated on `prizes` and kept current after every play; when disabled (default) those fields are omitted. See `getMiniGames` "Per-prize statistics"
+- `relative_period_timezone` (number) — Timezone offset in minutes used to evaluate the template's period-based rules (UTC minus local, as in JS `Date.getTimezoneOffset()` — e.g. `-180` for UTC+3)
+- `activeFromDate` (number) — Time from which the template becomes available (epoch ms); absent when not restricted
+- `activeTillDate` (number) — Time until which the template stays available (epoch ms); absent when not restricted
+- `steps_to_finish_game` (number) — Number of steps to complete the game and collect the prize (step games — Voyager / Treasure Hunt)
+- `custom_section_id` (number) — ID of the operator-defined custom section (widget menu grouping) the mini-game is assigned to
+- `saw_template_ui_definition` (SAWTemplateUI) — Full raw UI definition of the mini-game (skin, colors, per-game visual settings) — see `SAWTemplateUI`. The commonly needed values are already lifted onto this template object
   - `skin` (string)
   - `name` (string)
   - `description` (string)
@@ -124,11 +127,11 @@ Array of `TMiniGameTemplate`. Each item:
 		id: string;
 		content: string;
 	})
-- `game_layout` (SAWGameLayoutName) — The layout of the game
-- `show_prize_history` (boolean) — When enabled the prize history icon is visible on a certain template
+- `game_layout` (SAWGameLayoutName) — Grid layout of the game. Populated only for Lootbox game types (LootboxWeekdays / LootboxCalendarDays)
+- `show_prize_history` (boolean) — Operator setting: show a prize-history entry point (icon / button) on this game's view
 - `max_number_of_attempts` (number) — The maximum number of attempts that user can do during period of time
 - `max_spins_period_ms` (number) — The period of time in milliseconds during which the user can do the maximum number of attempts
-- `expose_user_spin_id` (SAWExposeUserSpinIdName) — The ID of the user spin id to expose on the game
+- `expose_user_spin_id` (SAWExposeUserSpinIdName) — Which identifier to show next to a win result for transparency/audit — 'userId' (the player's external user id) or 'spinId' (the spin's transaction id). Absent when the operator disabled it
 
 ## Behavioral contract
 **Subscription model (`onUpdate`)**
@@ -166,6 +169,27 @@ played via `playMiniGame`; the exceptions are:
  games server (not this SDK); the SAW spin is fired
  server-internally to deduct the buy-in.
 
+**Per-prize statistics (`expose_game_stat_on_api`)**
+Each template's `prizes` array always carries the definition
+fields — name, icon, `prize_type`, `prize_value`, acknowledge
+configuration. The stock-statistics fields are gated by an
+operator template setting, surfaced as
+`expose_game_stat_on_api`:
+- Populated when enabled: `pool` (remaining stock),
+ `wins_count` (total wins across all players), `weekdays`
+ (ISO 1–7 days the prize can be won), `active_from_ts` /
+ `active_till_ts` (prize availability window).
+- Omitted when disabled (the default) — this keeps the live
+ prize economy (stock levels, win rates, schedules) hidden
+ from players.
+- Exception: `pool` is always populated for `MatchX` / `Quiz`
+ templates, whose game flow needs the remaining stock.
+- `pool_initial` is populated regardless of the setting.
+When enabled, the values are also kept current — the server
+refreshes the prize rows on each fetch and drops its template
+caches after every play, so `pool` / `wins_count` are safe to
+drive an "X prizes left" scarcity UI.
+
 **Cache TTL**: the SDK caches the response for 30 seconds. Cache
 is fully cleared on login / logout.