@smartico/public-api 0.0.410 → 0.0.412

package/dist/index.modern.mjs

@@ -535,6 +535,7 @@ const 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,
@@ -3278,18 +3279,46 @@ 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(...)`
@@ -7199,7 +7228,11 @@ 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
@@ -7229,6 +7262,8 @@ 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
@@ -9997,6 +10032,7 @@ class SmarticoAPI {
           t.prizes.forEach(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);
           });
         }
       });