@smartico/public-api 0.0.409 → 0.0.411

package/docs/capabilities/miniGameWinAcknowledgeRequest.md

@@ -1,16 +1,17 @@
 # miniGameWinAcknowledgeRequest — API
 
-> Manually acknowledges a mini-game spin — marks the win delivered server-side.
+> Manually acknowledges a mini-game spin — marks the win delivered server-side, or (with `lose: true`) finalises it as lost and returns the prize to the pool.
 > Import: `import { /* types */ } from '@smartico/public-api'`
 > Search terms: miniGameWinAcknowledgeRequest, minigames, doSAWAcknowledge, SAWAcknowledge, acknowledge, SAWAcknowledgeType, request_id, errCode, errMsg, cid, ts, uuid, payload, duration
 
 ## Signature
 ```ts
-_smartico.api.miniGameWinAcknowledgeRequest(request_id: string): void
+_smartico.api.miniGameWinAcknowledgeRequest(request_id: string, { lose }: { lose?: boolean } = {}): void
 ```
 
 ## Parameters
 - `request_id` — Correlation id of the spin to finalise: the `request_id` from a `playMiniGame` result (played with `acknowledge: false`), or the `client_request_id` of a `getMiniGamesHistory` row.
+- `options.lose` — Optional. When `true`, finalises the spin as lost — the prize is not credited and returns to the prize pool (see "Finalising as lost"). Omit (or pass `false`) to deliver the win.
 
 ## Returns
 _No return value._
@@ -34,6 +35,27 @@ The `request_id` on a `playMiniGame` result and the
 `client_request_id` on a `getMiniGamesHistory` row are the
 same correlation id — this method accepts either.
 
+**Finalising as lost (`lose: true`)**
+Pass `{ lose: true }` to finalise the spin as LOST instead of won:
+the prize is NOT credited and is returned to the game's prize pool
+(available again for other players), and the spin fires the
+mini-game "lose" engagement event instead of the win one. On the
+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 (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
+spin, `lose: true` is a no-op and the prize stays credited.
+("Explicit claim" prizes are exempt from the fallback, so for them
+there is no time pressure.)
+
 **Idempotency**: safe. Acknowledging a spin that is already
 finalised — by you, by the automatic acknowledge, or by the
 fallback — is a no-op with no double credit. Acknowledging a
@@ -48,13 +70,16 @@ exception — excluded from the fallback, they require an explicit
 call here.
 
 **Side effects** (first successful call for an un-acknowledged spin)
-- For "explicit claim" prizes, the prize value is credited on this
- call. For standard prizes the value was already credited at spin
- time (see `playMiniGame` "Prize handling"); this call only
- marks the win delivered.
-- The spin's `is_claimed` flips to `true` on the next
+- Default (win): the prize value is credited on this call — this is
+ the finalisation step that credits standard and "explicit claim"
+ prizes alike (see `playMiniGame` "Prize handling").
+- With `lose: true`: no credit; the prize returns to the prize pool
+ and the "lose" engagement event fires.
+- 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
@@ -66,6 +91,10 @@ if (r.err_code === 0) {
   await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
 }
 
+// Decline / forfeit — finalise the same spin as lost instead:
+// the prize is not credited and goes back to the prize pool.
+await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id, { lose: true });
+
 // Recovery — re-acknowledge any spins a batch acknowledge missed.
 const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
 for (const row of history.filter(h => !h.is_claimed)) {

package/docs/capabilities/playMiniGame.md

@@ -67,14 +67,19 @@ without waiting for the win to be marked delivered. You finalise
 it later by calling `miniGameWinAcknowledgeRequest` with the
 `request_id` returned on this result.
 
-What `acknowledge: false` does and does NOT defer:
-- For STANDARD prizes the value is credited at spin time
- regardless, so opting out does NOT delay the balance change —
- it only defers the "delivered" bookkeeping and the `is_claimed`
- flag flipping in `getMiniGamesHistory`.
-- For operator-configured "explicit claim" prizes the credit IS
- deferred until the spin is acknowledged, so those require an
- explicit acknowledge to finalise.
+What `acknowledge: false` defers:
+- For STANDARD prizes the value is credited when the spin is
+ finalised — by your later acknowledge or, failing that, by the
+ server-side fallback below — so opting out delays the balance
+ change by at most that fallback window. The `is_claimed` flag in
+ `getMiniGamesHistory` flips on the same finalisation.
+- For operator-configured "explicit claim" prizes the credit is
+ deferred until your explicit acknowledge — the fallback does not
+ cover them.
+
+While the spin is un-finalised it can also be finalised as LOST —
+prize discarded back to the pool — via
+`miniGameWinAcknowledgeRequest` with `{ lose: true }`.
 
 A server-side fallback auto-acknowledges ordinary un-acknowledged
 spins after a short delay (about 1–3 minutes), so an ordinary
@@ -105,8 +110,10 @@ refreshed array.
  time the call resolves. Balance updates flow via the
  user-properties channel (observe via `getUserProfile`).
 - Prize value credited per the prize's type (see "Prize handling"
- above). Standard prizes are credited at spin time; "explicit
- claim" prizes are credited when the spin is acknowledged.
+ above) when the spin is finalised — with the default
+ auto-acknowledge that happens before the call resolves;
+ "explicit claim" prizes are credited only by an explicit
+ acknowledge.
 - The play is recorded server-side for analytics / reporting.
 
 **UI guidance**: see [UI Guide — `playMiniGame`](../../docs/ui/minigames/UIGuide_playMiniGame.md).
@@ -153,18 +160,24 @@ if (r.err_code === 0) {
 ```
 
 Manual finalisation (`acknowledge: false`) — e.g. an explicit
-"Claim" CTA, or finalising on your own schedule:
+"Claim" CTA, a decline/forfeit flow, or finalising on your own
+schedule:
 ```ts
 const r = await window._smartico.api.playMiniGame(game.id, { acknowledge: false });
 if (r.err_code === 0) {
-  // Spin resolved but not yet acknowledged. For standard prizes the
-  // balance already changed server-side; "explicit claim" prizes
-  // are credited only by the acknowledge below.
+  // Spin resolved but not yet finalised — the prize is not credited
+  // yet. Your acknowledge below credits it (for standard prizes the
+  // server-side fallback would eventually do the same).
   console.log('[smartico] prize won — show the result / Claim CTA, then finalise');
 
   // On the user's Claim click, finalise with the request_id from the result.
   await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
   console.log('[smartico] win finalised — refresh getUserProfile / getMiniGames to reflect it');
+
+  // Or, if the game flow ends in the player declining / losing the
+  // drawn prize, finalise the spin as lost instead — the prize is
+  // not credited and returns to the prize pool:
+  // await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id, { lose: true });
 }
 ```
 

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
@@ -1434,6 +1436,8 @@ Each item in `results`:
 
 Acknowledge a mini-game win. Should be called after displaying the win result to the user.
 
+Optionally finalises the spin as **lost** instead: with `lose: true` the prize is not credited, it is returned to the game's prize pool, and the mini-game "lose" engagement event fires instead of the win one. Only possible while the spin is not yet acknowledged — once the automatic server-side acknowledge fallback has finalised it, `lose: true` is a no-op and the prize stays credited.
+
 #### Request
 
 **ClassId:** `704` (SAW_AKNOWLEDGE_REQUEST)
@@ -1441,6 +1445,7 @@ Acknowledge a mini-game win. Should be called after displaying the win result to
 | Field | Type | Description |
 |-------|------|-------------|
 | `request_id` | `string` | Request ID from the spin response |
+| `lose` | `boolean` | Optional. `true` finalises the spin as lost: prize not credited, returned to the prize pool. Omit or `false` to deliver the win |
 
 #### Response
 
@@ -1506,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/jackpots/UIGuide_getJackpotEligibleGames.md

@@ -61,6 +61,14 @@ manually if needed.
 - For long sessions, re-call when reopening the tab past the 30 s
   window.
 
+## 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 sees the same
+list an identified user would. The `lang` passed to `_smartico.vapi(lang)`
+drives the translation of game names.
+
 ## Mobile vs desktop
 
 - **Mobile**: 2- or 3-column tile grid.

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):
@@ -99,6 +121,30 @@ error.
 | `promo_image` | ~2:1 wide, 500×240 px | Featured / hero artwork |
 | `prizes[].icon` | 1:1 (square) | Per-prize icon |
 
+## Prize stock / scarcity UI (`expose_game_stat_on_api`)
+
+When the operator enables "expose game statistics" on a template
+(`template.expose_game_stat_on_api === true`), each prize carries
+live stock statistics you can build scarcity affordances from:
+
+- `pool` — remaining stock → "Only 3 left!" badges; pair with
+  `pool_initial` for a depletion bar (`pool / pool_initial`).
+- `wins_count` — total wins across all players → social proof
+  ("won 120 times").
+- `weekdays` (ISO 1–7) and `active_from_ts` / `active_till_ts` —
+  the prize's availability schedule → grey out prizes not winnable
+  today, or show "available Mon–Fri" hints. Evaluate against
+  `relative_period_timezone` (minutes, JS `getTimezoneOffset`
+  convention), not the device timezone.
+
+The values refresh after every play, so re-render stock badges
+from the `onUpdate` callback. When the setting is disabled (the
+default) these fields are absent — build the prize strip from the
+definition fields only and don't reserve empty space for stock
+badges. Exception: `pool` is always present for MatchX / Quiz
+templates. A prize with `is_surcharge: true` never runs out —
+skip stock badges for it.
+
 ## Status-specific visual treatments
 
 - **Playable**: full-color card; Play CTA enabled.

package/docs/ui/minigames/UIGuide_getMiniGamesHistory.md

@@ -24,7 +24,7 @@ Fields rendered per row:
 | Field | Source | Notes |
 |---|---|---|
 | Template icon | `template.thumbnail` (or similar) | 1:1 |
-| Prize name | Look up `template.prizes[i]` by `saw_prize_id` | Display the prize's `name`. |
+| Prize name | Look up `template.prizes[i]` by `saw_prize_id` | Display the prize's `name`. A spin finalised as lost (`miniGameWinAcknowledgeRequest` with `lose: true`) has no prize attached — render it as a loss. |
 | Prize amount | `template.prizes[i].prize_value` or `prize_amount` | E.g. "100 points" |
 | Spin date | `create_date_ts` | Format as user-local relative time ("2h ago") or short date |
 | Claim status | `is_claimed` | Show check-mark when true; "Pending claim" CTA when false |

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

@@ -91,20 +91,56 @@ with the `request_id` from that play result when the user taps Claim.
 [`getMiniGamesHistory`](../../api/classes/WSAPIMiniGames.md#getminigameshistory)
 row if you need to recover it later.) Note: "explicit claim" prizes
 are NOT covered by the server-side auto-acknowledge fallback, so for
-these you MUST acknowledge or the prize is never credited.
+these you MUST acknowledge or the prize is never credited. To let
+the user decline the prize instead of claiming it, see "Decline /
+forfeit" below.
 
 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)
 - Optional additional CTA: `prize.acknowledge_action_title_additional`
   + `prize.acknowledge_dp_additional`
 
+## Decline / forfeit ("lose") flows
+
+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 (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.
+3. Finalise per the outcome:
+   - Keep / win →
+     `miniGameWinAcknowledgeRequest(request_id)` — prize credited.
+   - Decline / lose →
+     `miniGameWinAcknowledgeRequest(request_id, { lose: true })` —
+     prize NOT credited, returned to the prize pool for other
+     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
+server-side fallback after ~1–3 minutes, so send the lose decision
+promptly — after the fallback fires, `lose: true` is a no-op and
+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.409",
+	"version": "0.0.411",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/src/MiniGames/SAWDoAknowledgeRequest.ts

@@ -2,4 +2,6 @@ import { ProtocolMessage } from '.././Base/ProtocolMessage';
 
 export interface SAWDoAknowledgeRequest extends ProtocolMessage {
 	request_id: string; // guid
+	/** When true, finalises the spin as lost: the prize is not credited and is returned to the prize pool. */
+	lose?: boolean;
 }

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,22 +3,40 @@ 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;
+	/** Initial (configured) stock. Present regardless of `expose_game_stat_on_api` */
 	pool_initial?: number;
+	/** Times the prize has been won, across all players. Present only when `expose_game_stat_on_api` is enabled */
 	wins_count?: number;
+	/** ISO weekday numbers (1 = Monday … 7 = Sunday) the prize can be won on; absent = any day. Present only when `expose_game_stat_on_api` is enabled */
 	weekdays?: number[];
+	/** Prize availability window start (epoch ms), evaluated against `relative_period_timezone`. Present only when `expose_game_stat_on_api` is enabled */
 	active_from_ts?: number;
+	/** Prize availability window end (epoch ms), evaluated against `relative_period_timezone`. Present only when `expose_game_stat_on_api` is enabled */
 	active_till_ts?: number;
+	/** Timezone offset in minutes for `weekdays` / active-window evaluation (UTC minus local, as in JS `Date.getTimezoneOffset()`) */
 	relative_period_timezone?: number;
+	/** When true, the prize stays winnable at `pool` 0 (unlimited stock) */
 	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;
@@ -44,11 +64,14 @@ export interface SAWTemplate {
 		lottie_animation_speed?: number;
 	};
 
+	/** 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,
+						);
 					});
 				}
 			});
@@ -680,12 +685,13 @@ class SmarticoAPI {
 		return SAWTemplatesTransform((await this.sawGetTemplates(user_ext_id)).templates);
 	}
 
-	public async doAcknowledgeRequest(user_ext_id: string, request_id: string): Promise<SAWDoAknowledgeResponse> {
+	public async doAcknowledgeRequest(user_ext_id: string, request_id: string, lose?: boolean): Promise<SAWDoAknowledgeResponse> {
 		const message = this.buildMessage<SAWDoAknowledgeRequest, SAWDoAknowledgeResponse>(
 			user_ext_id,
 			ClassId.SAW_AKNOWLEDGE_REQUEST,
 			{
 				request_id,
+				lose,
 			},
 		);
 

package/src/SmarticoLib/index.ts

@@ -2021,7 +2021,7 @@ declare class SmarticoAPI {
 	coreCheckSegments(user_ext_id: string, segment_id: number[]): Promise<TSegmentCheckResult[]>;
 	sawGetTemplates(user_ext_id: string, lang?: string, is_visitor_mode?: boolean): Promise<SAWGetTemplatesResponse>;
 	sawGetTemplatesT(user_ext_id: string): Promise<TMiniGameTemplate[]>;
-	doAcknowledgeRequest(user_ext_id: string, request_id: string): Promise<SAWDoAknowledgeResponse>;
+	doAcknowledgeRequest(user_ext_id: string, request_id: string, lose?: boolean): Promise<SAWDoAknowledgeResponse>;
 	sawSpinRequest(user_ext_id: string, saw_template_id: number, round_id?: number): Promise<SAWDoSpinResponse>;
 	missionOptIn(user_ext_id: string, mission_id: number): Promise<AchievementOptinResponse>;
 	missionClaimPrize(user_ext_id: string, mission_id: number, ach_completed_id: number): Promise<AchClaimPrizeResponse>;