@smartico/public-api 0.0.410 → 0.0.412

package/README.md

@@ -73,7 +73,7 @@ The SDK surface is split across one class per feature area, joined by an interna
 | **Clans** | [`WSAPIClans`](docs/api/classes/WSAPIClans.md) | `getClans`, `getClanInfo`, `joinClan` | [`getClans`](docs/ui/clans/UIGuide_getClans.md) · [`getClanInfo`](docs/ui/clans/UIGuide_getClanInfo.md) · [`joinClan`](docs/ui/clans/UIGuide_joinClan.md) |
 | **Jackpots** | [`WSAPIJackpots`](docs/api/classes/WSAPIJackpots.md) | `jackpotGet`, `jackpotOptIn`, `jackpotOptOut`, `getJackpotWinners`, `getJackpotEligibleGames` | [`jackpotGet`](docs/ui/jackpots/UIGuide_jackpotGet.md) · [`jackpotOptIn`](docs/ui/jackpots/UIGuide_jackpotOptIn.md) · [`jackpotOptOut`](docs/ui/jackpots/UIGuide_jackpotOptOut.md) · [`getJackpotWinners`](docs/ui/jackpots/UIGuide_getJackpotWinners.md) · [`getJackpotEligibleGames`](docs/ui/jackpots/UIGuide_getJackpotEligibleGames.md) |
 | **Raffles / Draws** | [`WSAPIRaffles`](docs/api/classes/WSAPIRaffles.md) | `getRaffles`, `getRaffleDrawRun`, `getRaffleDrawRunsHistory`, `claimRafflePrize`, `requestRaffleOptin`, `getRaffleWonPrizes` | [`getRaffles`](docs/ui/raffles/UIGuide_getRaffles.md) · [`getRaffleDrawRun`](docs/ui/raffles/UIGuide_getRaffleDrawRun.md) · [`getRaffleDrawRunsHistory`](docs/ui/raffles/UIGuide_getRaffleDrawRunsHistory.md) · [`claimRafflePrize`](docs/ui/raffles/UIGuide_claimRafflePrize.md) · [`requestRaffleOptin`](docs/ui/raffles/UIGuide_requestRaffleOptin.md) · [`getRaffleWonPrizes`](docs/ui/raffles/UIGuide_getRaffleWonPrizes.md) |
-| **MiniGames / SAW** | [`WSAPIMiniGames`](docs/api/classes/WSAPIMiniGames.md) | `getMiniGames`, `getMiniGamesHistory`, `playMiniGame`, `miniGameWinAcknowledgeRequest`, `playMiniGameBatch` | [`getMiniGames`](docs/ui/minigames/UIGuide_getMiniGames.md) · [`getMiniGamesHistory`](docs/ui/minigames/UIGuide_getMiniGamesHistory.md) · [`playMiniGame`](docs/ui/minigames/UIGuide_playMiniGame.md) · [`playMiniGameBatch`](docs/ui/minigames/UIGuide_playMiniGameBatch.md) |
+| **MiniGames / SAW** | [`WSAPIMiniGames`](docs/api/classes/WSAPIMiniGames.md) | `getMiniGames`, `getMiniGamesHistory`, `playMiniGame`, `miniGameWinAcknowledgeRequest`, `playMiniGameBatch` | [`getMiniGames`](docs/ui/minigames/UIGuide_getMiniGames.md) · [`getMiniGamesHistory`](docs/ui/minigames/UIGuide_getMiniGamesHistory.md) · [`playMiniGame`](docs/ui/minigames/UIGuide_playMiniGame.md) · [`miniGameWinAcknowledgeRequest`](docs/ui/minigames/UIGuide_miniGameWinAcknowledgeRequest.md) · [`playMiniGameBatch`](docs/ui/minigames/UIGuide_playMiniGameBatch.md) |
 | **Avatars** | [`WSAPIAvatars`](docs/api/classes/WSAPIAvatars.md) | `getAvatarsList`, `getAvatarsCustomized`, `getAvatarPrompts`, `setAvatar`, `avatarsCustomize` | [`getAvatarsList`](docs/ui/avatars/UIGuide_getAvatarsList.md) · [`getAvatarsCustomized`](docs/ui/avatars/UIGuide_getAvatarsCustomized.md) · [`getAvatarPrompts`](docs/ui/avatars/UIGuide_getAvatarPrompts.md) · [`setAvatar`](docs/ui/avatars/UIGuide_setAvatar.md) · [`avatarsCustomize`](docs/ui/avatars/UIGuide_avatarsCustomize.md) |
 | **Game Pick (sports / quiz)** | [`WSAPIGamePick`](docs/api/classes/WSAPIGamePick.md) | `gamePickGet*`, `gamePickSubmit*` (9 methods) | [`gamePickGetActiveRounds`](docs/ui/gamepick/UIGuide_gamePickGetActiveRounds.md) · [`gamePickGetActiveRound`](docs/ui/gamepick/UIGuide_gamePickGetActiveRound.md) · [`gamePickGetHistory`](docs/ui/gamepick/UIGuide_gamePickGetHistory.md) · [`gamePickGetBoard`](docs/ui/gamepick/UIGuide_gamePickGetBoard.md) · [`gamePickSubmitSelection`](docs/ui/gamepick/UIGuide_gamePickSubmitSelection.md) · [`gamePickSubmitSelectionQuiz`](docs/ui/gamepick/UIGuide_gamePickSubmitSelectionQuiz.md) · [`gamePickGetUserInfo`](docs/ui/gamepick/UIGuide_gamePickGetUserInfo.md) · [`gamePickGetGameInfo`](docs/ui/gamepick/UIGuide_gamePickGetGameInfo.md) · [`gamePickGetRoundInfoForUser`](docs/ui/gamepick/UIGuide_gamePickGetRoundInfoForUser.md) |
 | **Leaderboard** | [`WSAPILeaderBoard`](docs/api/classes/WSAPILeaderBoard.md) | `getLeaderBoard`, `getLeaderBoards` | [`getLeaderBoard`](docs/ui/leaderboard/UIGuide_getLeaderBoard.md) |

package/dist/Jackpots/JackpotPublicMeta.d.ts

@@ -17,7 +17,7 @@ interface JackpotPublicMeta {
     /**
      * Custom data as string or JSON string that can be used in API to build custom UI
      * You can request from Smartico to define fields for your specific case that will be managed from Smartico BackOffice
-     * Read more here - <https://help.smartico.ai/welcome/products/general-concepts/custom-fields-attributes>
+     * Read more here - <https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes>
     */
     custom_data: string;
 }

package/dist/Level/LevelPublicMeta.d.ts

@@ -17,7 +17,7 @@ export interface LevelPublicMeta {
     /**
      * Custom data as string or JSON string that can be used in API to build custom UI
      * You can request from Smartico to define fields for your specific case that will be managed from Smartico BackOffice
-     * Read more here - https://help.smartico.ai/welcome/products/general-concepts/custom-fields-attributes
+     * Read more here - https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes
     */
     custom_data?: string;
 }

package/dist/MiniGames/SAWPrize.d.ts

@@ -2,12 +2,19 @@ import { AttemptPeriodType } from './AttemptPeriodType';
 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;
@@ -27,8 +34,10 @@ 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/dist/MiniGames/SAWPrizeUI.d.ts

@@ -7,6 +7,7 @@ export interface SAWPrizeUI {
     name_original?: string;
     hide_prize_popup: boolean;
     aknowledge_message?: string;
+    /** Message shown instead of `aknowledge_message` when the spin is finalised as lost (`lose: true` acknowledge — games with a client-decided outcome, e.g. Voyager) */
     aknowledge_message_lose?: string;
     sectors?: number[];
     acknowledge_type?: SAWAcknowledgeType;

package/dist/MiniGames/SAWTemplate.d.ts

@@ -3,29 +3,49 @@ import { SAWGameType } from './SAWGameType';
 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;
+    /** 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. */
     earliest_expiration_dt?: number | null;
     /** 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;
@@ -34,7 +54,12 @@ 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;
+    /** Prize Drop only: when true, the pushed prize requires an explicit claim by the user before it is credited */
     requires_prize_claim?: boolean;
+    /** Prize Drop only: when true, the pushed prize requires a manual claim by the user before it is credited. The difference between this and `requires_prize_claim` is that requires_manual_claim gives the user the ability to cancel the claim. */
+    requires_manual_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;
+    /** Operator setting: show a prize-history entry point (icon / button) on this game's view */
     show_prize_history?: boolean;
 }

package/dist/Raffle/Raffle.d.ts

@@ -23,7 +23,7 @@ interface RafflePublicMeta {
     /**
      * Custom data as string or JSON string that can be used in API to build custom UI
      * You can request from Smartico to define fields for your specific case that will be managed from Smartico BackOffice
-     * Read more here - <https://help.smartico.ai/welcome/products/general-concepts/custom-fields-attributes>
+     * Read more here - <https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes>
      */
     custom_data: string;
     /**

package/dist/SmarticoLib/index.d.ts

@@ -854,21 +854,21 @@ export interface TLevel {
     /**
      * The counter of 1st metric used to reach the Level.
      * Relevant in case of using advanced leveling logic
-     * https://help.smartico.ai/welcome/more/release-notes/september-2022#new-logic-for-leveling-users
+     * https://help.smartico.ai/welcome/products/release-notes/september-2022#new-logic-for-leveling-users
      *
      */
     required_level_counter_1: number;
     /**
      * The counter of 2nd metric used to reach the Level.
      * Relevant in case of using advanced leveling logic
-     * https://help.smartico.ai/welcome/more/release-notes/september-2022#new-logic-for-leveling-users
+     * https://help.smartico.ai/welcome/products/release-notes/september-2022#new-logic-for-leveling-users
      *
      */
     required_level_counter_2: number;
     /**
      * Custom data as string or JSON string that can be used in API to build custom UI
      * You can request from Smartico to define fields for your specific case that will be managed from Smartico BackOffice
-     * Read more here - https://help.smartico.ai/welcome/products/general-concepts/custom-fields-attributes
+     * Read more here - https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes
      */
     custom_data: string;
 }

package/dist/WSAPI/WSAPIMiniGames.d.ts

@@ -453,7 +453,11 @@ export declare 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
@@ -483,6 +487,8 @@ export declare 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

package/dist/WSAPI/WSAPIMissions.d.ts

@@ -55,18 +55,46 @@ export declare class WSAPIMissions extends WSAPIGeneral {
      * `only_in_custom_section: true` are intended for their custom-section
      * view only and should be hidden from the main mission list.
      *
-     * **Reading state from the returned mission**
-     * Drive availability chips ("missed", "coming soon", "needs opt-in",
-     * "in progress", "expired") from `availability_status` (enum
-     * {@link AchievementAvailabilityStatus}) — it's the canonical derived
-     * state and reflects all server-side timing/visibility rules in one
-     * field. For time-limited and recurring missions, `dt_start` doubles
-     * as the opt-in timestamp (for opt-in missions) or unlock timestamp
-     * (for previously-locked missions); the expiration of a time-limited
-     * mission is `dt_start + time_limit_ms`. `next_recurrence_date_ts`
-     * is populated for `RECURRING` / `RECURRING_QUANTITY` missions but
-     * is no longer meaningful once the mission's `active_till_ts` has
-     * passed.
+     * **Status bucketing (which tab / section a mission belongs to)**
+     * There is no pre-computed bucket field — assign each mission to exactly
+     * ONE section reading the raw state fields directly (NOT `availability_status`;
+     * see "Timers" below). Priority order, FIRST match wins:
+     * 1. **Missed / Expired** — not completed and the window has closed:
+     *    `!is_completed && ((time_limit_ms && dt_start && dt_start + time_limit_ms < Date.now())`
+     *    `|| (active_till_ts && active_till_ts < Date.now()))`. Do NOT gate this on
+     *    opt-in — an opt-in mission whose window closed before the user ever
+     *    opted in is still Missed. Sort by `position` ASC.
+     * 2. **Completed** — `is_completed === true`, OR (recurring-upon-completion
+     *    missions) at least one cycle done / the cap reached — see the recurring
+     *    caveats below. Sort by `complete_date_ts` DESC.
+     * 3. **Locked** — `is_locked === true`, OR not yet started
+     *    (`active_from_ts > Date.now()`). Sort by `position` ASC.
+     * 4. **In-progress** — `is_opted_in === true`, OR (no opt-in required and
+     *    `progress > 0`). Sort by `position` ASC.
+     * 5. **Available** — everything else (opt-in required but not yet joined, or
+     *    an unrestricted mission not yet started). Sort by `position` ASC.
+     *
+     * **Recurring-upon-completion caveats** (the common mis-bucketing trap):
+     * - `is_completed` NEVER flips true for a recurring-upon-completion mission
+     *   (only for one-shot missions) — detect a completed cycle from
+     *   `completion_count > 0`, not `is_completed`.
+     * - A non-null `completion_count` is what identifies a recurring-upon-completion
+     *   mission. `max_completion_count === null` means an INFINITE cap (still
+     *   recurring — never read null as "not recurring"), so only test
+     *   `completion_count >= max_completion_count` when `max_completion_count` is set.
+     *
+     * **Timers & timestamps** (display only — NOT bucketing)
+     * `availability_status` (enum {@link AchievementAvailabilityStatus}) is the
+     * timer/window signal: use it to pick WHICH countdown to show and whether the
+     * window has elapsed — NOT to choose the section. It does not read
+     * `completion_count`, and between cycles the server may keep reporting the
+     * just-elapsed cycle's `Missed*` value even after `dt_start` / `active_till_ts`
+     * are cleared for the next attempt, so bucketing by it sends recurring missions
+     * to the wrong tab. For time-limited / opt-in missions `dt_start` is the opt-in
+     * timestamp (or unlock timestamp for previously-locked missions), and a
+     * time-limited mission expires at `dt_start + time_limit_ms`.
+     * `next_recurrence_date_ts` is populated for `RECURRING` / `RECURRING_QUANTITY`
+     * missions but is no longer meaningful once `active_till_ts` has passed.
      *
      * **Refresh after a mutation**
      * After `requestMissionOptIn(...)` or `requestMissionClaimReward(...)`

package/dist/WSAPI/WSAPITypes.d.ts

@@ -20,39 +20,41 @@ 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.
      * 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;
@@ -74,17 +76,17 @@ export interface TMiniGamePrize {
     is_surcharge?: boolean;
     /** 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;
 }
 /**
@@ -158,10 +160,9 @@ 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;
     /** Soonest-expiring spin's expiration time for the current user, as an epoch-ms timestamp.
@@ -177,7 +178,7 @@ export interface TMiniGameTemplate {
     over_limit_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. */
     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;
@@ -190,25 +191,25 @@ export interface TMiniGameTemplate {
     promo_text: string;
     /** 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[];
     /** 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;
     /** 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;
@@ -825,7 +826,9 @@ export interface TMissionOrBadge {
     reward: string;
     /** URL of the image of the mission or badge, 256x256px */
     image: string;
-    /** Indicator if the mission is completed or badge is granted */
+    /** Indicator if the mission is completed or badge is granted. Stays `false` for
+     * Recurring-upon-completion missions even after cycles complete — use `completion_count`
+     * to detect completed cycles (see `getMissions` bucketing). */
     is_completed: boolean;
     /** Indicator if the mission is locked. Means that it's visible to the user, but he cannot progress in it until it's unlocked.
      * Mission may optionally contain the explanation of what should be done to unlock it in the unlock_mission_description property
@@ -897,15 +900,15 @@ export interface TMissionOrBadge {
     completed_this_month?: boolean;
     /** ID of specific Custom Section type */
     custom_section_type_id?: number;
-    /** Max number of times the user can complete a mission in case if mission type is Recurring upon completion. NULL equals infinite. */
+    /** Max number of times the user can complete a mission in case if mission type is Recurring upon completion. NULL equals infinite (still recurring — not "no cap disables recurring"). */
     max_completion_count?: number;
-    /** Current completion count for Recurring upon completion missions */
+    /** Current completion count for Recurring-upon-completion missions. Non-null ONLY for that mission type, so its presence identifies one; `> 0` means at least one cycle completed. */
     completion_count?: number;
     /** The date/timestamp for recurring missions, which indicating the time remaining until the next recurrence of the mission.
      * Note that if a mission has an "Active till" date defined, this field is not relevant after that date.
     */
     next_recurrence_date_ts?: number;
-    /** Availability status of the mission depends on the defined time limits */
+    /** Timer/window state derived from the mission's time limits (which countdown to show / whether the window elapsed). NOT a tab-bucketing signal — it ignores `completion_count`, so bucket sections from the raw fields instead (see `getMissions`). */
     availability_status?: AchievementAvailabilityStatus;
     /** Title for the claim reward button */
     claim_button_title?: string;
@@ -1342,7 +1345,7 @@ export interface TRaffle {
     /**
      * Custom data as string or JSON string that can be used in API to build custom UI
      * You can request from Smartico to define fields for your specific case that will be managed from Smartico BackOffice
-     * Read more here - https://help.smartico.ai/welcome/products/general-concepts/custom-fields-attributes
+     * Read more here - https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes
      */
     custom_data: string;
     /** Date of start */

package/dist/index.js

@@ -538,6 +538,7 @@ var SAWTemplatesTransform = function SAWTemplatesTransform(items) {
           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,
@@ -3408,18 +3409,46 @@ var WSAPIMissions = /*#__PURE__*/function (_WSAPIGeneral) {
    * `only_in_custom_section: true` are intended for their custom-section
    * view only and should be hidden from the main mission list.
    *
-   * **Reading state from the returned mission**
-   * Drive availability chips ("missed", "coming soon", "needs opt-in",
-   * "in progress", "expired") from `availability_status` (enum
-   * {@link AchievementAvailabilityStatus}) — it's the canonical derived
-   * state and reflects all server-side timing/visibility rules in one
-   * field. For time-limited and recurring missions, `dt_start` doubles
-   * as the opt-in timestamp (for opt-in missions) or unlock timestamp
-   * (for previously-locked missions); the expiration of a time-limited
-   * mission is `dt_start + time_limit_ms`. `next_recurrence_date_ts`
-   * is populated for `RECURRING` / `RECURRING_QUANTITY` missions but
-   * is no longer meaningful once the mission's `active_till_ts` has
-   * passed.
+   * **Status bucketing (which tab / section a mission belongs to)**
+   * There is no pre-computed bucket field — assign each mission to exactly
+   * ONE section reading the raw state fields directly (NOT `availability_status`;
+   * see "Timers" below). Priority order, FIRST match wins:
+   * 1. **Missed / Expired** — not completed and the window has closed:
+   *    `!is_completed && ((time_limit_ms && dt_start && dt_start + time_limit_ms < Date.now())`
+   *    `|| (active_till_ts && active_till_ts < Date.now()))`. Do NOT gate this on
+   *    opt-in — an opt-in mission whose window closed before the user ever
+   *    opted in is still Missed. Sort by `position` ASC.
+   * 2. **Completed** — `is_completed === true`, OR (recurring-upon-completion
+   *    missions) at least one cycle done / the cap reached — see the recurring
+   *    caveats below. Sort by `complete_date_ts` DESC.
+   * 3. **Locked** — `is_locked === true`, OR not yet started
+   *    (`active_from_ts > Date.now()`). Sort by `position` ASC.
+   * 4. **In-progress** — `is_opted_in === true`, OR (no opt-in required and
+   *    `progress > 0`). Sort by `position` ASC.
+   * 5. **Available** — everything else (opt-in required but not yet joined, or
+   *    an unrestricted mission not yet started). Sort by `position` ASC.
+   *
+   * **Recurring-upon-completion caveats** (the common mis-bucketing trap):
+   * - `is_completed` NEVER flips true for a recurring-upon-completion mission
+   *   (only for one-shot missions) — detect a completed cycle from
+   *   `completion_count > 0`, not `is_completed`.
+   * - A non-null `completion_count` is what identifies a recurring-upon-completion
+   *   mission. `max_completion_count === null` means an INFINITE cap (still
+   *   recurring — never read null as "not recurring"), so only test
+   *   `completion_count >= max_completion_count` when `max_completion_count` is set.
+   *
+   * **Timers & timestamps** (display only — NOT bucketing)
+   * `availability_status` (enum {@link AchievementAvailabilityStatus}) is the
+   * timer/window signal: use it to pick WHICH countdown to show and whether the
+   * window has elapsed — NOT to choose the section. It does not read
+   * `completion_count`, and between cycles the server may keep reporting the
+   * just-elapsed cycle's `Missed*` value even after `dt_start` / `active_till_ts`
+   * are cleared for the next attempt, so bucketing by it sends recurring missions
+   * to the wrong tab. For time-limited / opt-in missions `dt_start` is the opt-in
+   * timestamp (or unlock timestamp for previously-locked missions), and a
+   * time-limited mission expires at `dt_start + time_limit_ms`.
+   * `next_recurrence_date_ts` is populated for `RECURRING` / `RECURRING_QUANTITY`
+   * missions but is no longer meaningful once `active_till_ts` has passed.
    *
    * **Refresh after a mutation**
    * After `requestMissionOptIn(...)` or `requestMissionClaimReward(...)`
@@ -7669,7 +7698,11 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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
@@ -7699,6 +7732,8 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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
@@ -10885,6 +10920,7 @@ var SmarticoAPI = /*#__PURE__*/function () {
               t.prizes.forEach(function (p) {
                 p.saw_prize_ui_definition.name = IntUtils.replaceAll(p.saw_prize_ui_definition.name, '{{jackpot}}', jackpotValue);
                 p.saw_prize_ui_definition.aknowledge_message = IntUtils.replaceAll(p.saw_prize_ui_definition.aknowledge_message, '{{jackpot}}', jackpotValue);
+                p.saw_prize_ui_definition.aknowledge_message_lose = IntUtils.replaceAll(p.saw_prize_ui_definition.aknowledge_message_lose, '{{jackpot}}', jackpotValue);
               });
             }
           });