@smartico/public-api 0.0.409 → 0.0.411

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,
@@ -5990,7 +5991,7 @@ 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**
@@ -6008,7 +6009,12 @@ 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).
    *
@@ -6026,6 +6032,10 @@ 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);
    * ```
    */
   async getJackpotEligibleGames({
@@ -6768,6 +6778,27 @@ 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.
    *
@@ -6981,14 +7012,19 @@ 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
@@ -7019,8 +7055,10 @@ 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).
@@ -7085,18 +7123,24 @@ 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 });
    * }
    * ```
    */
@@ -7121,9 +7165,10 @@ 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.
    *
@@ -7146,6 +7191,27 @@ 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
@@ -7160,13 +7226,16 @@ 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
@@ -7174,6 +7243,10 @@ 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
@@ -7184,6 +7257,10 @@ 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)) {
@@ -7192,8 +7269,10 @@ class WSAPIMiniGames extends WSAPIRaffles {
    * }
    * ```
    */
-  async miniGameWinAcknowledgeRequest(request_id) {
-    return this.api.doAcknowledgeRequest(this.userExtId, request_id);
+  async miniGameWinAcknowledgeRequest(request_id, {
+    lose
+  } = {}) {
+    return this.api.doAcknowledgeRequest(this.userExtId, request_id, lose);
   }
   /**
    * Plays a mini-game template `spin_count` times in one round-trip.
@@ -9925,6 +10004,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);
           });
         }
       });
@@ -9934,9 +10014,10 @@ class SmarticoAPI {
   async sawGetTemplatesT(user_ext_id) {
     return SAWTemplatesTransform((await this.sawGetTemplates(user_ext_id)).templates);
   }
-  async doAcknowledgeRequest(user_ext_id, request_id) {
+  async doAcknowledgeRequest(user_ext_id, request_id, lose) {
     const message = this.buildMessage(user_ext_id, ClassId.SAW_AKNOWLEDGE_REQUEST, {
-      request_id
+      request_id,
+      lose
     });
     return await this.send(message, ClassId.SAW_AKNOWLEDGE_RESPONSE);
   }