@smartico/public-api 0.0.410 → 0.0.412

package/docs/api/interfaces/TMissionOrBadge.md

@@ -64,7 +64,9 @@ URL of the image of the mission or badge, 256x256px
 
 > **is\_completed**: `boolean`
 
-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).
 
 ***
 
@@ -311,7 +313,7 @@ ID of specific Custom Section type
 
 > `optional` **max\_completion\_count?**: `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").
 
 ***
 
@@ -319,7 +321,7 @@ Max number of times the user can complete a mission in case if mission type is R
 
 > `optional` **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.
 
 ***
 
@@ -336,7 +338,7 @@ Note that if a mission has an "Active till" date defined, this field is not rele
 
 > `optional` **availability\_status?**: [`AchievementAvailabilityStatus`](../enumerations/AchievementAvailabilityStatus.md)
 
-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`).
 
 ***
 

package/docs/api/interfaces/TRaffle.md

@@ -56,7 +56,7 @@ URL of the mobile image that represents the raffle, 300x142px
 
 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
 
 ***
 

package/docs/capabilities/getBadges.md

@@ -21,7 +21,7 @@ Array of `TMissionOrBadge`. Each item:
 - `description` (string) — Description of the mission or badge, translated to the user language
 - `reward` (string) — Description of the mission reward if defined
 - `image` (string) — URL of the image of the mission or badge, 256x256px
-- `is_completed` (boolean) — Indicator if the mission is completed or badge is granted
+- `is_completed` (boolean) — 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_locked` (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
 - `unlock_mission_description` (string) — Optional explaination of what should be done to unlock the mission
 - `is_requires_optin` (boolean) — Indicator if the mission requires opt-in. Means that user should explicitly opt-in to the mission in order to start progressing in it
@@ -79,10 +79,10 @@ Array of `TMissionOrBadge`. Each item:
 - `completed_this_week` (boolean) — Flag for mission/badge indicating that mission/badge completed this week
 - `completed_this_month` (boolean) — Flag for mission/badge indicating that mission/badge completed this month
 - `custom_section_type_id` (number) — ID of specific Custom Section type
-- `max_completion_count` (number) — Max number of times the user can complete a mission in case if mission type is Recurring upon completion. NULL equals infinite.
-- `completion_count` (number) — Current completion count for Recurring upon completion missions
+- `max_completion_count` (number) — 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").
+- `completion_count` (number) — 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.
 - `next_recurrence_date_ts` (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.
-- `availability_status` (AchievementAvailabilityStatus) — Availability status of the mission depends on the defined time limits
+- `availability_status` (AchievementAvailabilityStatus) — 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`).
 - `claim_button_title` (string) — Title for the claim reward button
 - `claim_button_action` (string) — Action for the claim reward button
 - `prize_claim_expiration_date` (number) — The date/timestamp indicating when the mission claim will expire

package/docs/capabilities/getMiniGames.md

@@ -30,35 +30,36 @@ Array of `TMiniGameTemplate`. Each item:
 - `buyin_cost_gems` (number) — in case of charging type 'Gems', what is the gems amount will be deducted from user balance
 - `buyin_cost_diamonds` (number) — in case of charging type 'Diamonds', what is the diamonds amount will be deducted from user balance
 - `spin_count` (number) — in case of charging type 'Spin attempts', shows the current number of spin attempts that user has
-- `next_available_spin_ts` (number) — if the game is limit to the number of spins that user can do during period of time, this property shows the epoch time in UTC when the next attempt will be available. Note that you need to enable 'Show time to the next available spin' setting on mini-game template in the backoffice Important: this field will not be populated if “Max number of attempts a user can do” is set to value different from 1
+- `next_available_spin_ts` (number) — If the game limits the number of attempts per period of time, the epoch-ms time (UTC) when the next attempt becomes available. Populated only when the operator enabled the "show time to the next available spin" template setting, and only when the template's maximum attempts per period is 1.
 - `earliest_expiration_dt` (number | null) — Soonest-expiring spin's expiration time for the current user, as an epoch-ms timestamp. `null` when the user has no expirable spins for this template — spins only expire when the template defines a spin-expiration rule (Wheel of Fortune, Loot Boxes, etc.). Pair with `latest_expiration_dt` to render a "spins expire between X and Y" window.
 - `latest_expiration_dt` (number | null) — Latest-expiring spin's expiration time for the current user, as an epoch-ms timestamp. `null` when the user has no expirable spins; equals `earliest_expiration_dt` when a single expiration applies.
 - `over_limit_message` (string) — The message that should be shown to the user when he cannot play the game, server rejected attempt with error code SAWSpinErrorCode.SAW_FAILED_MAX_SPINS_REACHED
 - `no_attempts_message` (string) — The message that should be shown to the user when he cannot play the game because he doesn't have spin attempts or points.
-- `jackpot_current` (number) — Current jackpont amount, if jackpot is enabled.
+- `jackpot_current` (number) — Current jackpot amount, if jackpot is enabled.
 - `jackpot_add_on_attempt` (number) — The amount that will be added to the jackpot every time when somebody plays the game. Note that the contribution amount is abstract, means that no money or points are deducted from the user balance.
 - `jackpot_symbol` (string) — The symbol of jackpot that is giving the sense to the 'amount' E.g. the symbol could be EUR and connected to the amount it can indicate that amount is monetary, e.g. '100 EUR'. Or the symbol can be 'Free spins' and connected to the amount it can indicate that amount is number of free spins, e.g. '100 Free spins'.
 - `promo_image` (string) — The promo image, 500x240px
 - `promo_text` (string) — The promo text
 - `custom_data` (any) — The custom data of the mini-game defined by operator in the BackOffice. Can be a JSON object, string or number
-- `prizes` (TMiniGamePrize[]) — List of prizes for mini-games
+- `prizes` (TMiniGamePrize[]) — Prizes configured for this game — see `TMiniGamePrize`
   - `id` (number) — ID of the prize
-  - `name` (string) — The visual name of the prize
-  - `prize_type` (MiniGamePrizeTypeName) — The type of the prize, no-prize, points, bonus, manual, spin, jackpot
+  - `name` (string) — Display name of the prize, pre-translated; any jackpot placeholder in it arrives resolved to the live jackpot value
+  - `prize_type` (MiniGamePrizeTypeName) — The type of the prize — see `MiniGamePrizeTypeName` ('no-prize', 'points', 'gems-and-diamonds', 'spin', 'bonus', 'jackpot', 'raffle-ticket', 'mission', 'change-level', 'manual')
   - `prize_value` (number) — Numeric value of the prize in case it's 'points' or 'spin' type. For other types of prizes this value is not relevant. For example for prize '100 points' the prize_value will be 100. For '100 free spins' the prize_value will be 100.
-  - `font_size` (number) — Custom font size for the prize (desktop)
-  - `font_size_mobile` (number) — Custom font size for the prize (mobile)
+  - `font_size` (number) — Custom font size in px for rendering the prize name on the game surface (e.g. a wheel sector), desktop
+  - `font_size_mobile` (number) — Custom font size in px for the prize name, mobile; falls back to `font_size` when absent
   - `icon` (string) — The URL of the icon of the prize, aspect ratio 1:1
-  - `position` (number) — for scratch card defines position of prize in the list
-  - `sectors` (number[]) — List of sectors for the prize
-  - `acknowledge_type` (SAWAcknowledgeTypeName) — Type of acknowledge message for users
+  - `position` (number) — For Scratch Card games — relative order of the prize in the scratch grid (lower first). May be absent for other game types
+  - `sectors` (number[]) — For Spin-a-Wheel games — wheel sector indices this prize occupies. Absent for non-wheel games
+  - `acknowledge_type` (SAWAcknowledgeTypeName) — Which win modal the prize uses — see `SAWAcknowledgeTypeName` (Silent / QuickMessage / FullMessage / ExplicitAcknowledge)
   - `aknowledge_message` (string) — Message that will be shown to user in modal pop-up
-  - `acknowledge_dp` (string) — Deep link that will trigger some action in modal pop-up
-  - `acknowledge_action_title` (string) — The name of the action button in modal pop-up
-  - `acknowledge_dp_additional` (string) — Deep link that will trigger some action in modal pop-up (additional)
-  - `acknowledge_action_title_additional` (string) — The name of the action button in modal pop-up (additional)
-  - `second_btn` (string) — Deep link that will trigger some action in modal pop-up (second button)
-  - `second_btn_action_title` (string) — The name of the action button in modal pop-up (second button)
+  - `aknowledge_message_lose` (string) — Message shown instead of `aknowledge_message` when the spin is finalised as lost (`lose: true` acknowledge flows — games with a client-decided outcome, e.g. Voyager). Absent unless configured
+  - `acknowledge_dp` (string) — Deep link executed when the user taps the main action button in the win modal (run it via `_smartico.dp()`)
+  - `acknowledge_action_title` (string) — Label of the main action button in the win modal
+  - `acknowledge_dp_additional` (string) — Deep link of the additional action button in the win modal
+  - `acknowledge_action_title_additional` (string) — Label of the additional action button in the win modal
+  - `second_btn` (string) — Deep link of the secondary button in the win modal
+  - `second_btn_action_title` (string) — Label of the secondary button in the win modal
   - `out_of_stock_message` (string) — Message when the prize pool is empty for that specific prize
   - `pool` (number) — Remaining stock of the prize — decrements on each win, refunded if the spin is finalised as lost. Populated only when the template's `expose_game_stat_on_api` is enabled; always populated for MatchX / Quiz games
   - `pool_initial` (number) — Initial (configured) stock of the prize. Populated regardless of `expose_game_stat_on_api`
@@ -69,19 +70,19 @@ Array of `TMiniGameTemplate`. Each item:
   - `relative_period_timezone` (number) — Timezone offset in minutes used to evaluate `weekdays` and the active window (UTC minus local, as in JS `Date.getTimezoneOffset()` — e.g. `-180` for UTC+3)
   - `is_surcharge` (boolean) — When true, the prize stays winnable even when its `pool` reaches 0 (effectively unlimited stock)
   - `is_deleted` (boolean) — Always `false` in API responses — deleted prizes are excluded server-side
-  - `custom_data` (any) — The custom data of the mini-game defined by operator in the BackOffice. Can be a JSON object, string or number
-  - `prize_modifiers` (PrizeModifiers[]) — Prize modifiers that will multiply by 2x, 5x or 10x the current total. This will not affect the final Prize Amount that will be awarded.
-  - `allow_split_decimal` (boolean) — When enabled, you can split prize value by decimal values
-  - `hide_prize_from_history` (boolean) — When enabled, you can hide prize from prize history
-  - `requirements_to_get_prize` (string) — Requirements to claim the prize (lootbox specific)
-  - `max_give_period_type_id` (AttemptPeriodType) — The period type for the prize to be given: Time from last attempt, Calendar days UTC, Calendar days user time zone, Lifetime
+  - `custom_data` (any) — The custom data of the prize defined by the operator. Can be a JSON object, string or number
+  - `prize_modifiers` (PrizeModifiers[]) — Step-modifier tiles for step games (Treasure Hunt / Voyager) — see `PrizeModifiers` (2x / 5x / 10x, /2 / /5 / /10, 0, reset) applied to the running total revealed during the game. Presentation only — the awarded amount is still `prize_value`
+  - `allow_split_decimal` (boolean) — Step games (Treasure Hunt / Voyager): when true, the per-step revealed amounts of the prize value may be fractional; when false the split uses whole numbers
+  - `hide_prize_from_history` (boolean) — Operator hint to hide this prize when rendering prize-history UIs. Informational only — API responses are not filtered by it
+  - `requirements_to_get_prize` (string) — Operator text describing what the user must do to be eligible for this prize (lootbox games); shown when the prize is not yet available to the user
+  - `max_give_period_type_id` (AttemptPeriodType) — Period basis for the prize availability restriction — see `AttemptPeriodType`. `CalendarDaysUserTimeZone` evaluates `weekdays` / the active window in the user's timezone; the other types use `relative_period_timezone`
 - `expose_game_stat_on_api` (boolean) — Operator template setting. When enabled, the per-prize stock statistics (`pool`, `wins_count`, `weekdays`, `active_from_ts` / `active_till_ts`) are populated on `prizes` and kept current after every play; when disabled (default) those fields are omitted. See `getMiniGames` "Per-prize statistics"
-- `relative_period_timezone` (number) — Time zone to ensure each day aligns with your local midnight.
-- `activeFromDate` (number) — Holds time from which template will become available, for the template that are targeted to be available from specific time (UNIX timestamp)
-- `activeTillDate` (number) — Holds time till which template will become available, for the templates that are targeted to be available from specific time (UNIX timestamp)
-- `steps_to_finish_game` (number) — The amount of steps to complete the game and gather the prize
+- `relative_period_timezone` (number) — Timezone offset in minutes used to evaluate the template's period-based rules (UTC minus local, as in JS `Date.getTimezoneOffset()` — e.g. `-180` for UTC+3)
+- `activeFromDate` (number) — Time from which the template becomes available (epoch ms); absent when not restricted
+- `activeTillDate` (number) — Time until which the template stays available (epoch ms); absent when not restricted
+- `steps_to_finish_game` (number) — Number of steps to complete the game and collect the prize (step games — Voyager / Treasure Hunt)
 - `custom_section_id` (number) — ID of the operator-defined custom section (widget menu grouping) the mini-game is assigned to
-- `saw_template_ui_definition` (SAWTemplateUI) — The UI definition of the mini-game
+- `saw_template_ui_definition` (SAWTemplateUI) — Full raw UI definition of the mini-game (skin, colors, per-game visual settings) — see `SAWTemplateUI`. The commonly needed values are already lifted onto this template object
   - `skin` (string)
   - `name` (string)
   - `description` (string)
@@ -126,8 +127,8 @@ Array of `TMiniGameTemplate`. Each item:
 		id: string;
 		content: string;
 	})
-- `game_layout` (SAWGameLayoutName) — The layout of the game
-- `show_prize_history` (boolean) — When enabled the prize history icon is visible on a certain template
+- `game_layout` (SAWGameLayoutName) — Grid layout of the game. Populated only for Lootbox game types (LootboxWeekdays / LootboxCalendarDays)
+- `show_prize_history` (boolean) — Operator setting: show a prize-history entry point (icon / button) on this game's view
 - `max_number_of_attempts` (number) — The maximum number of attempts that user can do during period of time
 - `max_spins_period_ms` (number) — The period of time in milliseconds during which the user can do the maximum number of attempts
 - `expose_user_spin_id` (SAWExposeUserSpinIdName) — Which identifier to show next to a win result for transparency/audit — 'userId' (the player's external user id) or 'spinId' (the spin's transaction id). Absent when the operator disabled it

package/docs/capabilities/getMissions.md

@@ -22,7 +22,7 @@ Array of `TMissionOrBadge`. Each item:
 - `description` (string) — Description of the mission or badge, translated to the user language
 - `reward` (string) — Description of the mission reward if defined
 - `image` (string) — URL of the image of the mission or badge, 256x256px
-- `is_completed` (boolean) — Indicator if the mission is completed or badge is granted
+- `is_completed` (boolean) — 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_locked` (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
 - `unlock_mission_description` (string) — Optional explaination of what should be done to unlock the mission
 - `is_requires_optin` (boolean) — Indicator if the mission requires opt-in. Means that user should explicitly opt-in to the mission in order to start progressing in it
@@ -80,10 +80,10 @@ Array of `TMissionOrBadge`. Each item:
 - `completed_this_week` (boolean) — Flag for mission/badge indicating that mission/badge completed this week
 - `completed_this_month` (boolean) — Flag for mission/badge indicating that mission/badge completed this month
 - `custom_section_type_id` (number) — ID of specific Custom Section type
-- `max_completion_count` (number) — Max number of times the user can complete a mission in case if mission type is Recurring upon completion. NULL equals infinite.
-- `completion_count` (number) — Current completion count for Recurring upon completion missions
+- `max_completion_count` (number) — 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").
+- `completion_count` (number) — 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.
 - `next_recurrence_date_ts` (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.
-- `availability_status` (AchievementAvailabilityStatus) — Availability status of the mission depends on the defined time limits
+- `availability_status` (AchievementAvailabilityStatus) — 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`).
 - `claim_button_title` (string) — Title for the claim reward button
 - `claim_button_action` (string) — Action for the claim reward button
 - `prize_claim_expiration_date` (number) — The date/timestamp indicating when the mission claim will expire
@@ -132,18 +132,46 @@ Client-side filtering you may still want: missions with
 `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
-`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 `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/docs/capabilities/getRaffles.md

@@ -21,7 +21,7 @@ Array of `TRaffle`. Each item:
 - `custom_section_id` (number) — ID of the custom section that is linked to the raffle in the Gamification widget
 - `image_url` (string) — URL of the image that represents the raffle, 890x193px
 - `image_url_mobile` (string) — URL of the mobile image that represents the raffle, 300x142px
-- `custom_data` (string) — 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
+- `custom_data` (string) — 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/tools-and-guides/custom-fields-attributes
 - `start_date` (number) — Date of start
 - `end_date` (number) — Date of end
 - `max_tickets_count` (number) — Maximum numer of tickets that can be given to all users for the whole period of raffle

package/docs/capabilities/jackpotGet.md

@@ -30,7 +30,7 @@ Array of `JackpotDetails`. Each item:
     - `content` (string)
   - `placeholder1` (string) — custom value of placeholder1 defined by operator and can be used in the HTML templates
   - `placeholder2` (string) — custom value of placeholder2 defined by operator and can be used in the HTML templates
-  - `custom_data` (string) — 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>
+  - `custom_data` (string) — 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/tools-and-guides/custom-fields-attributes>
 - `jp_currency` (string) — Native jackpot currency (ISO 4217). Used for winner-history amounts.
 - `user_currency` (string) — Current user's wallet currency. Used to display the pot via `pot.current_pot_amount_user_currency`.
 - `contribution_type` (JackpotContributionType) — Whether the contribution is a fixed amount or a percentage of the bet; see `JackpotContributionType`.

package/docs/capabilities/miniGameWinAcknowledgeRequest.md

@@ -44,7 +44,11 @@ next `getMiniGamesHistory` fetch the row shows `is_claimed:
 true` with no prize attached. Use this for game mechanics where the
 player can decline or forfeit the drawn prize — e.g. a
 gamble/discard step, or a client-driven game where the user's final
-action decides whether the pre-drawn prize is actually won. It only
+action decides whether the pre-drawn prize is actually won (the
+default Smartico UI does this for the Voyager game: failing the
+star-collection run finalises the spin as lost). When configured,
+the prize's `aknowledge_message_lose` is the operator's result copy
+for this case — show it instead of `aknowledge_message`. It only
 works on a spin that is not yet finalised, so it requires playing
 with `acknowledge: false` and calling promptly — once the automatic
 acknowledge or the server-side fallback (below) has finalised the
@@ -74,6 +78,8 @@ call here.
 - Either way the spin's `is_claimed` flips to `true` on the next
  `getMiniGamesHistory` fetch.
 
+**UI guidance**: see [UI Guide — `miniGameWinAcknowledgeRequest`](../../docs/ui/minigames/UIGuide_miniGameWinAcknowledgeRequest.md).
+
 **Visitor mode**: not supported.
 
 ## Example

package/docs/native/PROTOCOL.md

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

package/docs/ui/minigames/UIGuide_getMiniGames.md

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

package/docs/ui/minigames/UIGuide_miniGameWinAcknowledgeRequest.md

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

package/docs/ui/minigames/UIGuide_playMiniGame.md

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

package/docs/ui/missions/UIGuide_getMissions.md

@@ -13,31 +13,43 @@
   field. Consumers apply the bucketing filter chain below themselves.
 
 ## Status bucketing
-Partition the array using this **priority order — first match wins**:
+Partition the array using this **priority order — first match wins** —
+reading the raw state fields directly (NOT `availability_status`; see the
+note below):
 
-  1. **Missed** — time window passed before completion. Test:
-     `(!is_completed) && ((is_requires_optin && is_opted_in || !is_requires_optin)`
-     ` && time_limit_ms && dt_start && (dt_start + time_limit_ms) < Date.now())`
-     `|| (active_till_ts && active_till_ts < Date.now())`.
-     Sort: `position` ASC.
-  2. **Completed** — `is_completed === true`, OR for missions of type
-     `AchievementStatus.RecurringUponCompletion`,
-     `max_completion_count === completion_count` (cap reached) OR
-     `completion_count > 0` (at least one cycle completed).
+  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 still belongs in Missed. Sort: `position` ASC.
+  2. **Completed** — `is_completed === true`, OR (recurring-upon-completion
+     missions) at least one cycle done / the cap reached:
+     `completion_count > 0`, or `max_completion_count != null && completion_count >= max_completion_count`.
+     `is_completed` NEVER flips for recurring-upon-completion missions, so use
+     `completion_count`; a non-null `completion_count` is what identifies the
+     type, and `max_completion_count === null` means an INFINITE cap (still
+     recurring), so only compare against it when it is set.
      Sort: `complete_date_ts` DESC (most recent first).
   3. **Locked** — `is_locked === true`, OR not yet available
      (`active_from_ts > Date.now()`). Sort: `position` ASC.
-  4. **Available (in-progress)** — none of the above.
-     Sort: `position` ASC.
+  4. **In progress** — `is_opted_in === true`, OR (no opt-in required and
+     `progress > 0`). Sort: `position` ASC.
+  5. **Available** — everything else: opt-in required but not yet joined, or
+     an unrestricted mission not yet started. Sort: `position` ASC.
 
 Each mission belongs to exactly ONE bucket. Many UIs render these as
-status tabs / sections. The `availability_status` field
-([AchievementAvailabilityStatus](../../api/enumerations/AchievementAvailabilityStatus.md)) is authoritative for **timer /
-window state** (which countdown to show, whether the window has
-elapsed) — but it is NOT a substitute for bucketing: distinguishing
-"locked" from "opt-in required" requires reading `is_locked` and
-`is_opted_in` directly. An "Overview" tab curating featured +
-in-progress + a sample locked is a common pattern.
+status tabs / sections; an "Overview" tab curating featured + in-progress +
+a sample locked is a common pattern.
+
+**Do not bucket by `availability_status`.** That field
+([AchievementAvailabilityStatus](../../api/enumerations/AchievementAvailabilityStatus.md))
+is the **timer / window** signal only — which countdown to show, whether the
+window elapsed. It does NOT read `completion_count`, so for
+recurring-upon-completion missions it reports a stale `Missed*` value from the
+just-elapsed cycle even after `dt_start` / `active_till_ts` are cleared for the
+next attempt — using it to bucket sends recurring missions to the wrong tab.
+Distinguishing "locked" from "opt-in required" likewise needs `is_locked` /
+`is_opted_in` read directly.
 
 ## Mission card / tile (list view)
 
@@ -53,7 +65,10 @@ Fields to render on the card:
 - Description (fallback chain): `description` → `unlock_mission_description`
   (when `is_locked`) → `tasks[0].name` (when no description and tasks
   exist).
-- Progress bar — render only when `progress > 0` (the 0–100 integer).
+- Progress bar — render only when `progress > 0` (the 0–100 integer),
+  with one exception: a mission that requires opt-in and isn't opted in
+  yet (`is_requires_optin && !is_opted_in`) shows the bar at 0%, so the
+  card/modal signals it has a progress track waiting behind opt-in.
   Hide for completed recurring missions (`AchievementStatus.RecurringUponCompletion`
   on the Completed tab) to avoid showing residual percentage from a
   prior cycle.
@@ -103,8 +118,11 @@ Top-to-bottom structure (omit sections whose source field is empty):
       list is redundant). Each task row: completion indicator
       (checkbox/circle) + `task.name`. Append "N / M" using
       `execution_count_actual / execution_count_expected` when the
-      operator has enabled count display. Show a points stamp for
-      tasks with `points_reward > 0`.
+      operator has enabled count display. A single task can grant MORE
+      THAN ONE reward type — render one reward badge per non-zero amount
+      among `points_reward`, `gems_reward` and `diamonds_reward` (stack
+      them when a task grants several), each with that reward type's icon.
+      Don't assume points-only.
   13. Progress bar (conditional, same rule as card).
   14. Reward block (`reward`).
   15. Related games — only games where `game_public_meta.enabled === true`.
@@ -193,8 +211,10 @@ on click — it does NOT wait for the claim RPC to succeed. Consequences:
   Missions stay visible in the Missed bucket unless an operator
   config hides expired missions after N days.
 - **In progress**: default styling.
-- **Opt-in required**: same as in-progress; the status chip alone
-  signals "opt-in required".
+- **Opt-in required** (`is_requires_optin && !is_opted_in`): styled like
+  in-progress, but the status chip carries a "Requires opt-in" label
+  (not "Available") to signal the mission needs opt-in before progress
+  starts; pair it with the 0%-progress bar noted above.
 - **Featured**: replace the ribbon (when no `ribbon` is set) with a
   "featured" modifier; some brands use a gold border / glow.
 - **Claimable** (claim button visible): add a "claimable" modifier

package/package.json

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