@smartico/public-api 0.0.410 → 0.0.411

package/docs/api/classes/WSAPIMiniGames.md

@@ -546,7 +546,11 @@ next [getMiniGamesHistory](#getminigameshistory) fetch the row shows `is_claimed
 true` with no prize attached. Use this for game mechanics where the
 player can decline or forfeit the drawn prize — e.g. a
 gamble/discard step, or a client-driven game where the user's final
-action decides whether the pre-drawn prize is actually won. It only
+action decides whether the pre-drawn prize is actually won (the
+default Smartico UI does this for the Voyager game: failing the
+star-collection run finalises the spin as lost). When configured,
+the prize's `aknowledge_message_lose` is the operator's result copy
+for this case — show it instead of `aknowledge_message`. It only
 works on a spin that is not yet finalised, so it requires playing
 with `acknowledge: false` and calling promptly — once the automatic
 acknowledge or the server-side fallback (below) has finalised the
@@ -576,6 +580,8 @@ call here.
 - Either way the spin's `is_claimed` flips to `true` on the next
   [getMiniGamesHistory](#getminigameshistory) fetch.
 
+**UI guidance**: see [UI Guide — `miniGameWinAcknowledgeRequest`](../_media/UIGuide_miniGameWinAcknowledgeRequest.md).
+
 **Visitor mode**: not supported.
 
 #### Example

package/docs/api/interfaces/SAWPrize.md

@@ -6,42 +6,56 @@
 
 > **saw\_prize\_id**: `number`
 
+ID of the prize
+
 ***
 
 ### saw\_prize\_ui\_definition
 
 > **saw\_prize\_ui\_definition**: [`SAWPrizeUI`](SAWPrizeUI.md)
 
+Visual definition of the prize (name, icon, win-modal buttons, per-game rendering hints)
+
 ***
 
 ### prize\_value?
 
 > `optional` **prize\_value?**: `number`
 
+Numeric value for 'points' / 'spin' prize types (e.g. 100 for "100 points"); not relevant for other types
+
 ***
 
 ### prize\_type\_id
 
 > **prize\_type\_id**: [`SAWPrizeType`](../enumerations/SAWPrizeType.md)
 
+The type of the prize — see [SAWPrizeType](../enumerations/SAWPrizeType.md)
+
 ***
 
 ### place\_from?
 
 > `optional` **place\_from?**: `number`
 
+Competition games (MatchX / Quiz): first finishing place this prize applies to
+
 ***
 
 ### place\_to?
 
 > `optional` **place\_to?**: `number`
 
+Competition games (MatchX / Quiz): last finishing place this prize applies to; equals `place_from` for a single-place prize
+
 ***
 
 ### sawUniqueWinId?
 
 > `optional` **sawUniqueWinId?**: `string`
 
+Client-side only — unique id of a win instance generated by the default Smartico UI to dedupe render effects; never sent by the server
+
 ***
 
 ### pool?
@@ -120,6 +134,8 @@ Always `false` in API responses — deleted prizes are excluded server-side
 
 > `optional` **prize\_details\_json?**: `object`
 
+Type-specific prize details — e.g. `gems` / `_gems_diamonds_type` for gems-and-diamonds prizes, `tickets_count` for raffle-ticket prizes
+
 #### Index Signature
 
 \[`key`: `string`\]: `any`
@@ -129,3 +145,5 @@ Always `false` in API responses — deleted prizes are excluded server-side
 ### max\_give\_period\_type\_id?
 
 > `optional` **max\_give\_period\_type\_id?**: [`AttemptPeriodType`](../enumerations/AttemptPeriodType.md)
+
+Period basis for the prize availability restriction — see [AttemptPeriodType](../enumerations/AttemptPeriodType.md)

package/docs/api/interfaces/SAWPrizeUI.md

@@ -36,6 +36,8 @@
 
 > `optional` **aknowledge\_message\_lose?**: `string`
 
+Message shown instead of `aknowledge_message` when the spin is finalised as lost (`lose: true` acknowledge — games with a client-decided outcome, e.g. Voyager)
+
 ***
 
 ### sectors?

package/docs/api/interfaces/SAWTemplate.md

@@ -6,108 +6,144 @@
 
 > **saw\_template\_id**: `number`
 
+ID of the mini-game template
+
 ***
 
 ### saw\_game\_type\_id
 
 > **saw\_game\_type\_id**: [`SAWGameType`](../enumerations/SAWGameType.md)
 
+The type of the game — see [SAWGameType](../enumerations/SAWGameType.md)
+
 ***
 
 ### saw\_template\_ui\_definition
 
 > **saw\_template\_ui\_definition**: [`SAWTemplateUI`](SAWTemplateUI.md)
 
+Full UI definition of the mini-game (name, description, skin, colors, per-game visual settings)
+
 ***
 
 ### saw\_buyin\_type\_id
 
 > **saw\_buyin\_type\_id**: [`SAWBuyInType`](../enumerations/SAWBuyInType.md)
 
+How the user is charged per attempt — see [SAWBuyInType](../enumerations/SAWBuyInType.md)
+
 ***
 
 ### buyin\_cost\_points?
 
 > `optional` **buyin\_cost\_points?**: `number`
 
+Cost per attempt in the buy-in currency (points, gems or diamonds per `saw_buyin_type_id`)
+
 ***
 
 ### visibile\_when\_can\_spin
 
 > **visibile\_when\_can\_spin**: `boolean`
 
+Operator hint: show the game only while the user can actually play it (has attempts / sufficient balance)
+
 ***
 
 ### spin\_count?
 
 > `optional` **spin\_count?**: `number`
 
+Number of spin attempts the user currently has (initial value; later changes arrive as spin-count pushes)
+
 ***
 
 ### prizes
 
 > **prizes**: [`SAWPrize`](SAWPrize.md)[]
 
+Prizes configured for this game — see [SAWPrize](SAWPrize.md)
+
 ***
 
 ### is\_visible
 
 > **is\_visible**: `boolean`
 
+Operator visibility flag for the template
+
 ***
 
 ### activeFromDate?
 
 > `optional` **activeFromDate?**: `number`
 
+Time from which the template becomes available (epoch ms); absent when not restricted
+
 ***
 
 ### activeTillDate?
 
 > `optional` **activeTillDate?**: `number`
 
+Time until which the template stays available (epoch ms); absent when not restricted
+
 ***
 
 ### jackpot\_add\_on\_attempt
 
 > **jackpot\_add\_on\_attempt**: `number`
 
+Amount added to the jackpot on every play (abstract contribution — nothing is deducted from the player)
+
 ***
 
 ### jackpot\_current
 
 > **jackpot\_current**: `number`
 
+Current jackpot accumulator value
+
 ***
 
 ### jackpot\_guaranteed
 
 > **jackpot\_guaranteed**: `number`
 
+Seed value of the jackpot — the accumulator starts at (and resets to) this amount after a jackpot win
+
 ***
 
 ### maxActiveSpinsAllowed
 
 > **maxActiveSpinsAllowed**: `number`
 
+Maximum number of unspent spin attempts a user can accumulate
+
 ***
 
 ### maxSpinsCount
 
 > **maxSpinsCount**: `number`
 
+Maximum number of attempts a user can make during `maxSpinsPediodMs`
+
 ***
 
 ### maxSpinsPediodMs
 
 > **maxSpinsPediodMs**: `number`
 
+Length of the attempt-limit period in ms (note the field-name spelling)
+
 ***
 
 ### next\_available\_spin\_ts?
 
 > `optional` **next\_available\_spin\_ts?**: `number`
 
+Epoch-ms time when the next attempt becomes available; populated only when the operator enabled the "show time to the next available spin" setting and max attempts per period is 1
+
 ***
 
 ### earliest\_expiration\_dt?
@@ -130,12 +166,16 @@ Latest-expiring spin's expiration time for this user (epoch ms); `null`/absent w
 
 > **saw\_skin\_key**: `string`
 
+Key of the visual skin the operator selected for the game
+
 ***
 
 ### saw\_skin\_ui\_definition
 
 > **saw\_skin\_ui\_definition**: `object`
 
+Skin assets of the game: `skin_folder` is the base URL for the skin's images, `skin_css` custom CSS overrides, plus optional popup/animation tweaks
+
 #### skin\_folder
 
 > **skin\_folder**: `string`
@@ -166,14 +206,20 @@ Operator template setting. When enabled, the per-prize stock statistics (`pool`,
 
 > `optional` **requires\_prize\_claim?**: `boolean`
 
+Prize Drop only: when true, the pushed prize requires an explicit claim by the user before it is credited
+
 ***
 
 ### relative\_period\_timezone?
 
 > `optional` **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()`)
+
 ***
 
 ### show\_prize\_history?
 
 > `optional` **show\_prize\_history?**: `boolean`
+
+Operator setting: show a prize-history entry point (icon / button) on this game's view

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,7 @@ 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
 
 ***
 
@@ -129,7 +137,7 @@ The name of the action button in modal pop-up (additional)
 
 > `optional` **second\_btn?**: `string`
 
-Deep link that will trigger some action in modal pop-up (second button)
+Deep link of the secondary button in the win modal
 
 ***
 
@@ -137,7 +145,7 @@ Deep link that will trigger some action in modal pop-up (second button)
 
 > `optional` **second\_btn\_action\_title?**: `string`
 
-The name of the action button in modal pop-up (second button)
+Label of the secondary button in the win modal
 
 ***
 
@@ -225,7 +233,7 @@ Always `false` in API responses — deleted prizes are excluded server-side
 
 > `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
 
 ***
 
@@ -233,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`
 
 ***
 
@@ -241,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
 
 ***
 
@@ -249,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
 
 ***
 
@@ -257,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
 
 ***
 
@@ -265,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)
 
 ***
 
@@ -208,7 +207,7 @@ Operator template setting. When enabled, the per-prize stock statistics (`pool`,
 
 > `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)
 
 ***
 
@@ -248,7 +247,7 @@ ID of the operator-defined custom section (widget menu grouping) the mini-game i
 
 > **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
 
 ***