@smartico/public-api 0.0.408 → 0.0.410

package/docs/capabilities/getMiniGames.md

@@ -57,28 +57,30 @@ Array of `TMiniGameTemplate`. Each item:
   - `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)
   - `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
+  - `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 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
+- `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
-- `custom_section_id` (number) — Hold the id of the custom section
+- `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
   - `skin` (string)
   - `name` (string)
@@ -128,7 +130,7 @@ Array of `TMiniGameTemplate`. Each item:
 - `show_prize_history` (boolean) — When enabled the prize history icon is visible on a certain template
 - `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 +168,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.
 

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,23 @@ 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. 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,11 +66,12 @@ 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.
 
 **Visitor mode**: not supported.
@@ -66,6 +85,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

@@ -1434,6 +1434,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 +1443,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
 

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

@@ -99,6 +99,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_playMiniGame.md

@@ -91,7 +91,9 @@ 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:
 
@@ -105,6 +107,31 @@ Modal contents per prize:
 - 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. 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 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.
+
 ## "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.408",
+	"version": "0.0.410",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -24,7 +24,7 @@
 		"bump-ach": "cd ../tracker/ach && npm install @smartico/public-api@latest --legacy-peer-deps",
 		"bump-bo-server": "cd ../bo_server/server && source ~/.nvm/nvm.sh && nvm use v13.13.0 && npm install @smartico/public-api@latest",
 		"bump-bo-client": "cd ../bo_server/client && source ~/.nvm/nvm.sh && nvm use v13.13.0 && npm install @smartico/public-api@latest",
-		"doc": "typedoc && node scripts/postdoc-cleanup.js",
+		"doc": "node scripts/gen-capabilities.js && typedoc && node scripts/postdoc-cleanup.js",
 		"gen-capabilities": "node scripts/gen-capabilities.js"
 	},
 	"author": "",

package/src/GamePick/GamePickTypes.ts

@@ -233,7 +233,12 @@ export interface GamePickEvent {
 	resolution_score?: number;
 	/** Whether this event is still accepting predictions */
 	is_open_for_bets?: boolean;
-	/** Betting odds details for the event outcomes */
+	/** Per-outcome numbers keyed by the outcome value (`'1'` / `'x'` / `'2'`, `'yes'` / `'no'`, …).
+	 * Dual-purpose by event type:
+	 * - Sports / MatchX: decimal **betting odds** (e.g. `{ "1": 2.45, "x": 3.26, "2": 3.01 }`).
+	 * - Quiz: when the round's `show_users_preference` is `true`, these are aggregated
+	 *   **user-preference percentages** — what other users predicted, summing to ~100
+	 *   (e.g. `{ "1": 33, "x": 25, "2": 42 }`). Render as the "what others predicted" bar. */
 	odds_details?: { odd_value: { [key: string]: number } };
 	/** URL of a question-specific image (quiz events) */
 	question_image?: string;

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

@@ -77,6 +77,8 @@ export const SAWTemplatesTransform = (items: SAWTemplate[]): TMiniGameTemplate[]
 					acknowledge_action_title: p.saw_prize_ui_definition.acknowledge_action_title,
 					acknowledge_dp_additional: p.saw_prize_ui_definition.acknowledge_dp_additional,
 					acknowledge_action_title_additional: p.saw_prize_ui_definition.acknowledge_action_title_additional,
+					second_btn: p.saw_prize_ui_definition.second_btn,
+					second_btn_action_title: p.saw_prize_ui_definition.second_btn_action_title,
 					out_of_stock_message: p.saw_prize_ui_definition.out_of_stock_message,
 					pool: p.pool,
 					pool_initial: p.pool_initial,

package/src/MiniGames/SAWPrize.ts

@@ -10,14 +10,23 @@ export interface SAWPrize {
 	place_from?: number;
 	place_to?: number;
 	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;
 	prize_details_json?: {[key: string]: any};
 	max_give_period_type_id?: AttemptPeriodType;

package/src/MiniGames/SAWTemplate.ts

@@ -44,6 +44,7 @@ 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

package/src/SmarticoAPI.ts

@@ -680,12 +680,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>;

package/src/Tournaments/GetClanTournamentPlayersResponse.ts

@@ -1,4 +1,5 @@
 import { ProtocolResponse } from '../Base/ProtocolResponse';
+import { TClanTournamentPlayers } from '../WSAPI/WSAPITypes';
 
 export interface ClanTournamentPlayerRaw {
 	userId: number;
@@ -19,24 +20,10 @@ export interface GetClanTournamentPlayersResponse extends ProtocolResponse {
 	players: ClanTournamentPlayerRaw[];
 }
 
-export interface TClanTournamentPlayer {
-	user_id: number;
-	clean_ext_user_id: string;
-	public_username: string;
-	avatar_id: string;
-	avatar_real_id: number;
-	avatar_url?: string;
-	position: number;
-	scores: number;
-	is_me: boolean;
-}
-
-export interface TClanTournamentPlayersResult {
-	tournament_instance_id: number;
-	players: TClanTournamentPlayer[];
-}
-
-export const clanTournamentPlayersTransform = (response: GetClanTournamentPlayersResponse): TClanTournamentPlayersResult => {
+// Consumer-facing types live in WSAPITypes.ts (`TClanTournamentPlayers`) — the
+// single source documented + emitted to docs. This transform maps the raw wire
+// shape onto it; do not re-declare a parallel result/player type here.
+export const clanTournamentPlayersTransform = (response: GetClanTournamentPlayersResponse): TClanTournamentPlayers => {
 	return {
 		tournament_instance_id: response.tournament_instance_id,
 		players: (response.players || []).map((p) => ({

package/src/WSAPI/WSAPIJackpots.ts

@@ -396,7 +396,7 @@ export class WSAPIJackpots extends WSAPIClans {
 	 *
 	 * @remarks
 	 * **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**
@@ -414,7 +414,12 @@ export class WSAPIJackpots extends WSAPIClans {
 	 * 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).
 	 *
@@ -432,6 +437,10 @@ export class WSAPIJackpots extends WSAPIClans {
 	 *
 	 * 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);
 	 * ```
 	 */
 	public async getJackpotEligibleGames({ jp_template_id, onUpdate } : {