@smartico/public-api 0.0.409 → 0.0.411

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 } : {

package/src/WSAPI/WSAPIMiniGames.ts

@@ -64,6 +64,27 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 *   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.
 	 *
@@ -290,14 +311,19 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * it later by calling {@link 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 {@link 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
+	 *   {@link 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
+	 * {@link 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
@@ -328,8 +354,10 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 *   time the call resolves. Balance updates flow via the
 	 *   user-properties channel (observe via {@link 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).
@@ -394,18 +422,24 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 *
 	 * @example
 	 * 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 });
 	 * }
 	 * ```
 	 */
@@ -433,9 +467,10 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 
 	/**
 	 * Manually acknowledges a mini-game spin — marks the win delivered
-	 * server-side. Most consumers do NOT need this: {@link playMiniGame}
-	 * acknowledges by default (`acknowledge: true`) and
-	 * {@link playMiniGameBatch} acknowledges automatically. Call this
+	 * server-side, or (with `lose: true`) finalises it as lost and
+	 * returns the prize to the pool. Most consumers do NOT need this:
+	 * {@link playMiniGame} acknowledges by default (`acknowledge: true`)
+	 * and {@link playMiniGameBatch} acknowledges automatically. Call this
 	 * directly only when you took ownership of the acknowledge step or
 	 * need to recover a lost one.
 	 *
@@ -458,6 +493,27 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * `client_request_id` on a {@link 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 {@link 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
@@ -472,13 +528,16 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * 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 {@link 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 {@link 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
 	 *   {@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
@@ -486,6 +545,10 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 *                    (played with `acknowledge: false`), or the
 	 *                    `client_request_id` of a
 	 *                    {@link getMiniGamesHistory} row.
+	 * @param 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.
 	 *
 	 * @example
 	 * ```ts
@@ -496,6 +559,10 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 *   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)) {
@@ -504,8 +571,8 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * }
 	 * ```
 	 */
-	public async miniGameWinAcknowledgeRequest(request_id: string) {
-		return this.api.doAcknowledgeRequest(this.userExtId, request_id);
+	public async miniGameWinAcknowledgeRequest(request_id: string, { lose }: { lose?: boolean } = {}) {
+		return this.api.doAcknowledgeRequest(this.userExtId, request_id, lose);
 	}
 
 	/**

package/src/WSAPI/WSAPITypes.ts

@@ -23,71 +23,73 @@ type TRibbon = 'sale' | 'hot' | 'new' | 'vip' | string;
 export interface TMiniGamePrize {
 	/** ID of the prize */
 	id: number;
-	/** The visual name of the prize */
+	/** Display name of the prize, pre-translated; any jackpot placeholder in it arrives resolved to the live jackpot value */
 	name: string;
-	/** The type of the prize,  no-prize, points, bonus, manual, spin, jackpot */
+	/** The type of the prize — see {@link MiniGamePrizeTypeName} ('no-prize', 'points', 'gems-and-diamonds', 'spin', 'bonus', 'jackpot', 'raffle-ticket', 'mission', 'change-level', 'manual') */
 	prize_type: MiniGamePrizeTypeName;
-	/** Numeric value of the prize in case it's 'points' or 'spin' type. For other types of prizes this value is not relevant. 
+	/** Numeric value of the prize in case it's 'points' or 'spin' type. For other types of prizes this value is not relevant.
 	 * For example for prize  '100 points' the prize_value will be 100. For '100 free spins' the prize_value will be 100.
 	*/
 	prize_value?: number;
-	/** Custom font size for the prize (desktop) */
+	/** Custom font size in px for rendering the prize name on the game surface (e.g. a wheel sector), desktop */
 	font_size?: number;
-	/** Custom font size for the prize (mobile) */
+	/** Custom font size in px for the prize name, mobile; falls back to `font_size` when absent */
 	font_size_mobile?: number;
 	/** The URL of the icon of the prize, aspect ratio 1:1 */
 	icon?: string;
-	/** for scratch card defines position of prize in the list */
+	/** For Scratch Card games — relative order of the prize in the scratch grid (lower first). May be absent for other game types */
 	position: number;
-	/** List of sectors for the prize */
+	/** For Spin-a-Wheel games — wheel sector indices this prize occupies. Absent for non-wheel games */
 	sectors: number[];
-	/** Type of acknowledge message for users */
+	/** Which win modal the prize uses — see {@link SAWAcknowledgeTypeName} (Silent / QuickMessage / FullMessage / ExplicitAcknowledge) */
 	acknowledge_type: SAWAcknowledgeTypeName;
 	/** Message that will be shown to user in modal pop-up */
 	aknowledge_message: string;
-	/** Deep link that will trigger some action in modal pop-up */
+	/** 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 */
+	aknowledge_message_lose?: string;
+	/** Deep link executed when the user taps the main action button in the win modal (run it via `_smartico.dp()`) */
 	acknowledge_dp: string;
-	/** The name of the action button in modal pop-up */
+	/** Label of the main action button in the win modal */
 	acknowledge_action_title: string;
-	/** Deep link that will trigger some action in modal pop-up (additional) */
+	/** Deep link of the additional action button in the win modal */
 	acknowledge_dp_additional?: string;
-	/** The name of the action button in modal pop-up (additional) */
+	/** Label of the additional action button in the win modal */
 	acknowledge_action_title_additional?: string;
-	/** Deep link that will trigger some action in modal pop-up (second button) */
+	/** Deep link of the secondary button in the win modal */
 	second_btn?: string,
-	/** The name of the action button in modal pop-up (second button) */
+	/** Label of the secondary button in the win modal */
 	second_btn_action_title?: string;
 	/** Message when the prize pool is empty for that specific prize */
 	out_of_stock_message?: string;
-	/** Number of items in stock */
+	/** Remaining stock of the prize — decrements on each win, refunded if the spin is finalised as lost. Populated only when the template's `expose_game_stat_on_api` is enabled; always populated for MatchX / Quiz games */
 	pool?: number;
-	/** Initial number of items in stock */
+	/** Initial (configured) stock of the prize. Populated regardless of `expose_game_stat_on_api` */
 	pool_initial?: number;
-	/** Number of wins in game */
+	/** Number of times the prize has been won, across all players. Populated only when the template's `expose_game_stat_on_api` is enabled */
 	wins_count?: number;
-	/** Number of days of week, when the prize can be available */
+	/** ISO weekday numbers (1 = Monday … 7 = Sunday) on which the prize can be won; absent = any day. Populated only when the template's `expose_game_stat_on_api` is enabled */
 	weekdays?: number[];
-	/** Holds time from which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp) */
+	/** Time from which the prize can be won (epoch ms), evaluated against `relative_period_timezone`. Populated only when the template's `expose_game_stat_on_api` is enabled */
 	active_from_ts?: number;
-	/** Holds time till which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp) */
+	/** Time until which the prize can be won (epoch ms), evaluated against `relative_period_timezone`. Populated only when the template's `expose_game_stat_on_api` is enabled */
 	active_till_ts?: number;
-	/** Time zone to ensure each day aligns with your local midnight. */
+	/** Timezone offset in minutes used to evaluate `weekdays` and the active window (UTC minus local, as in JS `Date.getTimezoneOffset()` — e.g. `-180` for UTC+3) */
 	relative_period_timezone?: number;
-	/** Flag indicating that the prize is surcharged (available all the time, despite pool numbers) */
+	/** When true, the prize stays winnable even when its `pool` reaches 0 (effectively unlimited stock) */
 	is_surcharge?: boolean;
-	/** Flag indicating the state of the prize */
+	/** Always `false` in API responses — deleted prizes are excluded server-side */
 	is_deleted?: boolean;
-	/** The custom data of the mini-game defined by operator in the BackOffice. Can be a JSON object, string or number */
+	/** The custom data of the prize defined by the operator. Can be a JSON object, string or number */
 	custom_data?: any;
-	/** Prize modifiers that will multiply by 2x, 5x or 10x the current total. This will not affect the final Prize Amount that will be awarded. */
+	/** Step-modifier tiles for step games (Treasure Hunt / Voyager) — see {@link 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` */
 	prize_modifiers?: PrizeModifiers[];
-	/** When enabled, you can split prize value by decimal values */
+	/** Step games (Treasure Hunt / Voyager): when true, the per-step revealed amounts of the prize value may be fractional; when false the split uses whole numbers */
 	allow_split_decimal?: boolean;
-	/** When enabled, you can hide prize from prize history */
+	/** Operator hint to hide this prize when rendering prize-history UIs. Informational only — API responses are not filtered by it */
 	hide_prize_from_history?: boolean;
-	/** Requirements to claim the prize  (lootbox specific)*/
+	/** Operator text describing what the user must do to be eligible for this prize (lootbox games); shown when the prize is not yet available to the user */
 	requirements_to_get_prize?: string;
-	/** The period type for the prize to be given: Time from last attempt, Calendar days UTC, Calendar days user time zone, Lifetime */
+	/** Period basis for the prize availability restriction — see {@link AttemptPeriodType}. `CalendarDaysUserTimeZone` evaluates `weekdays` / the active window in the user's timezone; the other types use `relative_period_timezone` */
 	max_give_period_type_id?: AttemptPeriodType;
 }
 
@@ -167,11 +169,10 @@ export interface TMiniGameTemplate {
 	/** in case of charging type 'Spin attempts', shows the current number of spin attempts that user has */
 	spin_count?: number;
 
-	/** 
-	 * if the game is limit to the number of spins that user can do during period of time,
-	 * this property shows the epoch time in UTC when the next attempt will be available.
-	 * Note that you need to enable 'Show time to the next available spin' setting on mini-game template in the backoffice
-	 * Important: this field will not be populated if “Max number of attempts a user can do” is set to value different from 1
+	/**
+	 * If the game limits the number of attempts per period of time, the epoch-ms time (UTC) when the next attempt becomes available.
+	 * Populated only when the operator enabled the "show time to the next available spin" template setting, and only when the
+	 * template's maximum attempts per period is 1.
 	 * */
 	next_available_spin_ts: number;
 
@@ -190,7 +191,7 @@ export interface TMiniGameTemplate {
 	/** The message that should be shown to the user when he cannot play the game because he doesn't have spin attempts or points. */
 	no_attempts_message: string;
 
-	/** Current jackpont amount, if jackpot is enabled. */
+	/** Current jackpot amount, if jackpot is enabled. */
 	jackpot_current: 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_add_on_attempt: number;
@@ -205,34 +206,34 @@ export interface TMiniGameTemplate {
 	/** The custom data of the mini-game defined by operator in the BackOffice. Can be a JSON object, string or number */
 	custom_data: any;
 
-	/** List of prizes for mini-games */
+	/** Prizes configured for this game — see {@link TMiniGamePrize} */
 	prizes: TMiniGamePrize[];
 
-	/** When enabled, the number of items in the pool and number of won items will be exposed in the Retention API and in the UI Widgets */
+	/** Operator template setting. When enabled, the per-prize stock statistics (`pool`, `wins_count`, `weekdays`, `active_from_ts` / `active_till_ts`) are populated on `prizes` and kept current after every play; when disabled (default) those fields are omitted. See `getMiniGames` "Per-prize statistics" */
 	expose_game_stat_on_api?: boolean;
 
-	/** Time zone to ensure each day aligns with your local midnight. */
+	/** Timezone offset in minutes used to evaluate the template's period-based rules (UTC minus local, as in JS `Date.getTimezoneOffset()` — e.g. `-180` for UTC+3) */
 	relative_period_timezone?: number;
-	/** Holds time from which template will become available, for the template that are targeted to be available from specific time (UNIX timestamp) */
+	/** Time from which the template becomes available (epoch ms); absent when not restricted */
 	activeFromDate?: number;
-	/** Holds time till which template will become available, for the templates that are targeted to be available from specific time (UNIX timestamp) */
+	/** Time until which the template stays available (epoch ms); absent when not restricted */
 	activeTillDate?: number;
-	/** The amount of steps to complete the game and gather the prize */
+	/** Number of steps to complete the game and collect the prize (step games — Voyager / Treasure Hunt) */
 	steps_to_finish_game?: number;
-	/** Hold the id of the custom section */
+	/** ID of the operator-defined custom section (widget menu grouping) the mini-game is assigned to */
 	custom_section_id?: number;
 
-	/** The UI definition of the mini-game */
+	/** Full raw UI definition of the mini-game (skin, colors, per-game visual settings) — see {@link SAWTemplateUI}. The commonly needed values are already lifted onto this template object */
 	saw_template_ui_definition: SAWTemplateUI;
-	/** The layout of the game */
+	/** Grid layout of the game. Populated only for Lootbox game types (LootboxWeekdays / LootboxCalendarDays) */
 	game_layout?: SAWGameLayoutName;
-	/** When enabled the prize history icon is visible on a certain template */
+	/** Operator setting: show a prize-history entry point (icon / button) on this game's view */
 	show_prize_history?: boolean;
 	/** The maximum number of attempts that user can do during period of time */
 	max_number_of_attempts?: number;
 	/** The period of time in milliseconds during which the user can do the maximum number of attempts */
 	max_spins_period_ms?: number;
-	/** The ID of the user spin id to expose on the game */
+	/** Which identifier to show next to a win result for transparency/audit — 'userId' (the player's external user id) or 'spinId' (the spin's transaction id). Absent when the operator disabled it */
 	expose_user_spin_id?: SAWExposeUserSpinIdName;
 }