@smartico/public-api 0.0.410 → 0.0.411

package/docs/capabilities/getMiniGames.md

@@ -30,35 +30,36 @@ 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)
-  - `second_btn` (string) — Deep link that will trigger some action in modal pop-up (second button)
-  - `second_btn_action_title` (string) — The name of the action button in modal pop-up (second button)
+  - `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) — 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`
@@ -69,19 +70,19 @@ Array of `TMiniGameTemplate`. Each item:
   - `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 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
+  - `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) — 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
+- `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) — The UI definition of the mini-game
+- `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)
@@ -126,8 +127,8 @@ 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) — 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/miniGameWinAcknowledgeRequest.md

@@ -44,7 +44,11 @@ next `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
@@ -74,6 +78,8 @@ call here.
 - Either way the spin's `is_claimed` flips to `true` on the next
  `getMiniGamesHistory` fetch.
 
+**UI guidance**: see [UI Guide — `miniGameWinAcknowledgeRequest`](../../docs/ui/minigames/UIGuide_miniGameWinAcknowledgeRequest.md).
+
 **Visitor mode**: not supported.
 
 ## Example

package/docs/native/PROTOCOL.md

@@ -1329,6 +1329,8 @@ No method-specific fields. Send only the common fields (see [Common Message Fiel
 |-------|------|-------------|
 | `templates` | [`SAWTemplate[]`](../api/interfaces/SAWTemplate.md) | Array of mini-game templates |
 
+Note: per-prize stock statistics (`pool`, `wins_count`, `weekdays`, `active_from_ts` / `active_till_ts`) are present on each template's `prizes` only when the template's `expose_game_stat_on_api` is enabled; otherwise the server strips them (`pool` is kept for MatchX / Quiz game types).
+
 ---
 
 ### playMiniGame
@@ -1509,6 +1511,8 @@ Acknowledge a mini-game spin push. Sent after handling `SAW_SHOW_SPIN_PUSH` (707
 
 Acknowledge multiple mini-game wins at once. Used after `playMiniGameBatch`.
 
+The batch acknowledge always finalises spins as **won** — `lose` is not supported here. To finalise a spin as lost, send a single [miniGameWinAcknowledge](#minigamewinacknowledge) (704) with `lose: true`.
+
 #### Request
 
 **ClassId:** `714`

package/docs/ui/minigames/UIGuide_getMiniGames.md

@@ -75,6 +75,28 @@ keyed on `saw_game_type`. For custom UIs, render the matching
 component per game type — they share the same `playMiniGame`
 trigger (except `PrizeDrop`, `MatchX`, `Quiz` as noted).
 
+## Prize-field usage per game type
+
+Several `prizes[]` fields only matter for specific renderers:
+
+| Prize field | Used by | How |
+|---|---|---|
+| `sectors` | Spin-a-Wheel | Wheel sector indices the prize occupies — place the prize label/icon on those sectors. |
+| `position` | Scratch Card | Sort prizes ascending by `position` to lay out the scratch grid. |
+| `font_size` / `font_size_mobile` | Wheel, Scratch | Px size for the prize label on the game surface; mobile falls back to desktop. |
+| `prize_modifiers` | Treasure Hunt, Voyager | Modifier tiles (2x…/10, 0, reset) applied to the running revealed total — presentation only; the award is still `prize_value`. |
+| `allow_split_decimal` | Treasure Hunt, Voyager | Whether per-step revealed amounts may be fractional. |
+| `requirements_to_get_prize` | Lootboxes | Text shown when the prize isn't yet available to the user. |
+| `out_of_stock_message` | All (with stock) | Shown when the prize's pool is depleted. |
+| `icon`, `name` | All | Prize strip, game surface, win modal. `name` arrives with the live jackpot value inlined. |
+| `acknowledge_*`, `second_btn*`, `aknowledge_message(_lose)` | All | Win-modal contents — see [UI Guide — `playMiniGame`](UIGuide_playMiniGame.md) "Prize reveal modals". |
+
+Template-side companions: `game_layout` picks the Lootbox grid
+variant, `steps_to_finish_game` sizes step games, and
+`expose_user_spin_id` asks the win view to display the player's
+external user id (`'userId'`) or the spin's transaction id
+(`'spinId'`) for transparency/audit.
+
 ## Action button decision matrix
 
 CTA on the card / detail view (evaluate in priority order):

package/docs/ui/minigames/UIGuide_miniGameWinAcknowledgeRequest.md

@@ -0,0 +1,90 @@
+# UI Guide — `miniGameWinAcknowledgeRequest`
+
+Action-focused method — no list/card rendering of its own. It finalises
+a spin played with `acknowledge: false`: as **won** (default) or as
+**lost** (`{ lose: true }`). The UI patterns below cover the three
+call sites: an explicit Claim CTA, a decline/forfeit outcome, and
+history-row recovery.
+
+## When the UI calls this
+
+| Flow | Trigger | Call |
+|---|---|---|
+| Explicit claim | User taps "Claim" in the prize modal (`acknowledge_type === 'ExplicitAcknowledge'`) after `playMiniGame(id, { acknowledge: false })` | `miniGameWinAcknowledgeRequest(r.request_id)` |
+| Decline / forfeit | Game outcome or user choice says the drawn prize is NOT won (skill games like Voyager, gamble/discard steps) | `miniGameWinAcknowledgeRequest(r.request_id, { lose: true })` |
+| History recovery | User taps "Claim" on a `getMiniGamesHistory` row with `is_claimed === false` | `miniGameWinAcknowledgeRequest(row.client_request_id)` |
+
+## Action button decision matrix
+
+- **Win path (Claim CTA)**: enable the button as soon as the play
+  result is shown; disable it (with a spinner) while the request is
+  in flight; on resolve, show the prize's `aknowledge_message` modal
+  copy and refresh balance widgets (`getUserProfile`) and
+  `getMiniGames`.
+- **Lose path**: no user-facing "lose the prize" button in most
+  designs — the game flow decides. The default Smartico UI sends
+  `lose: true` when the Voyager run fails (not all stars collected),
+  then shows the prize's `aknowledge_message_lose` copy (fall back to
+  a generic "Better luck next time" treatment when the operator
+  didn't configure it).
+- **If you DO offer an explicit decline choice** (keep-or-gamble
+  UIs): render "Claim" and "Decline" side by side, disable both on
+  first tap, and treat the two calls as mutually exclusive — the
+  first one to reach the server wins; the other becomes a no-op.
+- **History recovery rows**: see
+  [UI Guide — `getMiniGamesHistory`](UIGuide_getMiniGamesHistory.md)
+  for the row-level Claim CTA.
+
+## Timing constraints (drive the UX)
+
+- Standard prizes are auto-finalised as WON by a server-side fallback
+  after ~1–3 minutes. A decline/forfeit decision must therefore be
+  sent promptly after the spin — don't park the choice behind an
+  unbounded modal. After the fallback fires, `lose: true` is a no-op
+  and the prize stays credited.
+- "Explicit claim" prizes are exempt from the fallback: the Claim CTA
+  can wait indefinitely, and an unclaimed prize is simply never
+  credited. Surface unclaimed spins via the history view.
+
+## Idempotency guard
+
+The call is idempotent server-side (no double credit), so a
+double-tap is harmless — but still disable the button in flight to
+avoid duplicate requests and modal flicker.
+
+## Result handling
+
+```ts
+const r = await window._smartico.api.playMiniGame(game.id, { acknowledge: false });
+if (r.err_code === 0) {
+  const prize = game.prizes.find(p => p.id === r.prize_id);
+  // ... run the game / show the Claim UI ...
+
+  if (playerWon) {
+    await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
+    console.log('[smartico] win finalised — show', prize?.aknowledge_message,
+      'and refresh getUserProfile / getMiniGames');
+  } else {
+    await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id, { lose: true });
+    console.log('[smartico] spin finalised as lost — show',
+      prize?.aknowledge_message_lose ?? 'a generic "Better luck next time" message');
+  }
+}
+```
+
+## Empty / loading / error states
+
+- In flight: spinner on the CTA, inputs locked.
+- On network failure: re-enable the CTA and let the user retry — the
+  operation is safe to repeat. For standard prizes the server-side
+  fallback will eventually deliver the win even if every retry fails
+  (a pending decline, however, is lost once the fallback fires).
+- No dedicated error codes: a non-zero `err_code` is a generic server
+  error — show a generic error toast.
+
+## Related guides
+
+- [UI Guide — `playMiniGame`](UIGuide_playMiniGame.md) — prize reveal
+  modals, `acknowledge_type` matrix, decline/forfeit flow.
+- [UI Guide — `getMiniGamesHistory`](UIGuide_getMiniGamesHistory.md) —
+  unclaimed-row recovery.

package/docs/ui/minigames/UIGuide_playMiniGame.md

@@ -100,7 +100,10 @@ Modal contents per prize:
 - Icon: `prize.icon` (1:1)
 - Title: `prize.name`
 - Message: `prize.aknowledge_message` (note the typo in the field
-  name — `aknowledge` not `acknowledge`)
+  name — `aknowledge` not `acknowledge`). When the spin is finalised
+  as lost (see "Decline / forfeit" below), show
+  `prize.aknowledge_message_lose` instead, falling back to a generic
+  "Better luck next time" when not configured.
 - CTA: `prize.acknowledge_action_title` with action
   `prize.acknowledge_dp` (pass through `_smartico.dp()` for safe
   execution)
@@ -112,7 +115,9 @@ Modal contents per prize:
 Some game mechanics let the player decline or forfeit the drawn
 prize — a gamble/discard step, a "keep it or risk it" offer, or a
 game where the player's final action decides whether the pre-drawn
-prize is actually won. Implement these with manual finalisation:
+prize is actually won (the default Smartico UI does this for the
+Voyager game: failing the star-collection run forfeits the drawn
+prize). Implement these with manual finalisation:
 
 1. Play with `acknowledge: false` so the SDK does not auto-finalise.
 2. Run the game / choice UI.
@@ -122,7 +127,8 @@ prize is actually won. Implement these with manual finalisation:
    - Decline / lose →
      `miniGameWinAcknowledgeRequest(request_id, { lose: true })` —
      prize NOT credited, returned to the prize pool for other
-     players. Show the same "Better luck next time" treatment as a
+     players. Show `prize.aknowledge_message_lose` when configured,
+     else the same "Better luck next time" treatment as a
      `no-prize` slot (below).
 
 Timing: standard prizes are auto-finalised as WON by the
@@ -132,6 +138,9 @@ the prize stays credited. "Explicit claim" prizes are exempt from
 the fallback, so those have no time pressure. Once a spin is
 finalised either way, further acknowledge calls are no-ops.
 
+Full CTA / retry / timing patterns: see
+[UI Guide — `miniGameWinAcknowledgeRequest`](UIGuide_miniGameWinAcknowledgeRequest.md).
+
 ## "No prize" handling
 
 When the won prize has `prize_type === 'no-prize'`, the user has

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smartico/public-api",
-	"version": "0.0.410",
+	"version": "0.0.411",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/src/MiniGames/SAWGetTemplatesResponse.ts

@@ -73,6 +73,7 @@ export const SAWTemplatesTransform = (items: SAWTemplate[]): TMiniGameTemplate[]
 					sectors: p.saw_prize_ui_definition.sectors,
 					acknowledge_type: SAWAcknowledgeTypeNamed(p.saw_prize_ui_definition.acknowledge_type),
 					aknowledge_message: p.saw_prize_ui_definition.aknowledge_message,
+					aknowledge_message_lose: p.saw_prize_ui_definition.aknowledge_message_lose,
 					acknowledge_dp: p.saw_prize_ui_definition.acknowledge_dp,
 					acknowledge_action_title: p.saw_prize_ui_definition.acknowledge_action_title,
 					acknowledge_dp_additional: p.saw_prize_ui_definition.acknowledge_dp_additional,

package/src/MiniGames/SAWPrize.ts

@@ -3,12 +3,19 @@ import { SAWPrizeType } from './SAWPrizeType';
 import { SAWPrizeUI } from './SAWPrizeUI';
 
 export interface SAWPrize {
+	/** ID of the prize */
 	saw_prize_id: number;
+	/** Visual definition of the prize (name, icon, win-modal buttons, per-game rendering hints) */
 	saw_prize_ui_definition: SAWPrizeUI;
+	/** Numeric value for 'points' / 'spin' prize types (e.g. 100 for "100 points"); not relevant for other types */
 	prize_value?: number;
+	/** The type of the prize — see {@link SAWPrizeType} */
 	prize_type_id: SAWPrizeType;
+	/** Competition games (MatchX / Quiz): first finishing place this prize applies to */
 	place_from?: number;
+	/** Competition games (MatchX / Quiz): last finishing place this prize applies to; equals `place_from` for a single-place prize */
 	place_to?: number;
+	/** Client-side only — unique id of a win instance generated by the default Smartico UI to dedupe render effects; never sent by the server */
 	sawUniqueWinId?: string;
 	/** Remaining stock. Present only when the template's `expose_game_stat_on_api` is enabled; always present for MatchX / Quiz games */
 	pool?: number;
@@ -28,6 +35,8 @@ export interface SAWPrize {
 	is_surcharge?: boolean;
 	/** Always `false` in API responses — deleted prizes are excluded server-side */
 	is_deleted?: boolean;
+	/** Type-specific prize details — e.g. `gems` / `_gems_diamonds_type` for gems-and-diamonds prizes, `tickets_count` for raffle-ticket prizes */
 	prize_details_json?: {[key: string]: any};
+	/** Period basis for the prize availability restriction — see {@link AttemptPeriodType} */
 	max_give_period_type_id?: AttemptPeriodType;
 }

package/src/MiniGames/SAWPrizeUI.ts

@@ -8,7 +8,8 @@ export interface SAWPrizeUI {
 	name_original?: string; // keeps original name, how it came from the servers. This is needed for the Jackpot value replacemenet
 	hide_prize_popup: boolean; // if true, prize popup on Prize Drop will not be shown
 	aknowledge_message?: string;
-	aknowledge_message_lose?: string; // voyager specific
+	/** 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) */
+	aknowledge_message_lose?: string;
 	sectors?: number[];
 	acknowledge_type?: SAWAcknowledgeType;
 	acknowledge_dp?: string;

package/src/MiniGames/SAWTemplate.ts

@@ -4,31 +4,49 @@ import { SAWPrize } from './SAWPrize';
 import { SAWTemplateUI } from './SAWTemplateUI';
 
 export interface SAWTemplate {
+	/** ID of the mini-game template */
 	saw_template_id: number;
+	/** The type of the game — see {@link SAWGameType} */
 	saw_game_type_id: SAWGameType;
+	/** Full UI definition of the mini-game (name, description, skin, colors, per-game visual settings) */
 	saw_template_ui_definition: SAWTemplateUI;
 
+	/** How the user is charged per attempt — see {@link SAWBuyInType} */
 	saw_buyin_type_id: SAWBuyInType;
+	/** Cost per attempt in the buy-in currency (points, gems or diamonds per `saw_buyin_type_id`) */
 	buyin_cost_points?: number;
+	/** Operator hint: show the game only while the user can actually play it (has attempts / sufficient balance) */
 	visibile_when_can_spin: boolean;
 
-	spin_count?: number; // inital count, after that server will push SAWSpinsCountPush
+	/** Number of spin attempts the user currently has (initial value; later changes arrive as spin-count pushes) */
+	spin_count?: number;
 
+	/** Prizes configured for this game — see {@link SAWPrize} */
 	prizes: SAWPrize[];
 
+	/** Operator visibility flag for the template */
 	is_visible: boolean;
 
+	/** Time from which the template becomes available (epoch ms); absent when not restricted */
 	activeFromDate?: number;
+	/** Time until which the template stays available (epoch ms); absent when not restricted */
 	activeTillDate?: number;
 
+	/** Amount added to the jackpot on every play (abstract contribution — nothing is deducted from the player) */
 	jackpot_add_on_attempt: number;
+	/** Current jackpot accumulator value */
 	jackpot_current: number;
+	/** Seed value of the jackpot — the accumulator starts at (and resets to) this amount after a jackpot win */
 	jackpot_guaranteed: number;
 
+	/** Maximum number of unspent spin attempts a user can accumulate */
 	maxActiveSpinsAllowed: number;
+	/** Maximum number of attempts a user can make during `maxSpinsPediodMs` */
 	maxSpinsCount: number;
+	/** Length of the attempt-limit period in ms (note the field-name spelling) */
 	maxSpinsPediodMs: 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 */
 	next_available_spin_ts?: number;
 
 	/** Soonest-expiring spin's expiration time for this user (epoch ms); `null`/absent when no expirable spins. */
@@ -36,7 +54,9 @@ export interface SAWTemplate {
 	/** Latest-expiring spin's expiration time for this user (epoch ms); `null`/absent when no expirable spins. */
 	latest_expiration_dt?: number | null;
 
+	/** Key of the visual skin the operator selected for the game */
 	saw_skin_key: string;
+	/** 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 */
 	saw_skin_ui_definition: {
 		skin_folder: string;
 		skin_css: string;
@@ -47,9 +67,11 @@ export interface SAWTemplate {
 	/** Operator template setting. When enabled, the per-prize stock statistics (`pool`, `wins_count`, `weekdays`, `active_from_ts` / `active_till_ts`) are populated on `prizes`; when disabled (default) the server strips them from the response (`pool` is kept for MatchX / Quiz games). */
 	expose_game_stat_on_api?: boolean;
 
-	// AA: releavnt only in the context of the SAWPrizeDropWinPush
+	/** Prize Drop only: when true, the pushed prize requires an explicit claim by the user before it is credited */
 	requires_prize_claim?: boolean;
-	
+
+	/** Timezone offset in minutes used to evaluate the template's period-based rules (UTC minus local, as in JS `Date.getTimezoneOffset()`) */
 	relative_period_timezone?: number;
-	show_prize_history?:boolean;
+	/** Operator setting: show a prize-history entry point (icon / button) on this game's view */
+	show_prize_history?: boolean;
 }

package/src/SmarticoAPI.ts

@@ -668,6 +668,11 @@ class SmarticoAPI {
 							'{{jackpot}}',
 							jackpotValue,
 						);
+						p.saw_prize_ui_definition.aknowledge_message_lose = IntUtils.replaceAll(
+							p.saw_prize_ui_definition.aknowledge_message_lose,
+							'{{jackpot}}',
+							jackpotValue,
+						);
 					});
 				}
 			});

package/src/WSAPI/WSAPIMiniGames.ts

@@ -502,7 +502,11 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * 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
@@ -532,6 +536,8 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * - Either way the spin's `is_claimed` flips to `true` on the next
 	 *   {@link getMiniGamesHistory} fetch.
 	 *
+	 * **UI guidance**: see [UI Guide — `miniGameWinAcknowledgeRequest`](../../docs/ui/minigames/UIGuide_miniGameWinAcknowledgeRequest.md).
+	 *
 	 * **Visitor mode**: not supported.
 	 *
 	 * @param request_id  Correlation id of the spin to finalise: the