@smartico/public-api 0.0.409 → 0.0.411

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,
@@ -6369,7 +6370,7 @@ var WSAPIJackpots = /*#__PURE__*/function (_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**
@@ -6387,7 +6388,12 @@ var WSAPIJackpots = /*#__PURE__*/function (_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).
    *
@@ -6405,6 +6411,10 @@ var WSAPIJackpots = /*#__PURE__*/function (_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);
    * ```
    */
   ;
@@ -7211,6 +7221,27 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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.
    *
@@ -7438,14 +7469,19 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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
@@ -7476,8 +7512,10 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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).
@@ -7542,18 +7580,24 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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 });
    * }
    * ```
    */
@@ -7591,9 +7635,10 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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.
    *
@@ -7616,6 +7661,27 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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
@@ -7630,13 +7696,16 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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
@@ -7644,6 +7713,10 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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
@@ -7654,6 +7727,10 @@ var WSAPIMiniGames = /*#__PURE__*/function (_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)) {
@@ -7663,10 +7740,12 @@ var WSAPIMiniGames = /*#__PURE__*/function (_WSAPIRaffles) {
    * ```
    */
   ;
-  _proto.miniGameWinAcknowledgeRequest = function miniGameWinAcknowledgeRequest(request_id) {
+  _proto.miniGameWinAcknowledgeRequest = function miniGameWinAcknowledgeRequest(request_id, _temp5) {
+    var _ref4 = _temp5 === void 0 ? {} : _temp5,
+      lose = _ref4.lose;
     try {
       var _this4 = this;
-      return Promise.resolve(_this4.api.doAcknowledgeRequest(_this4.userExtId, request_id));
+      return Promise.resolve(_this4.api.doAcknowledgeRequest(_this4.userExtId, request_id, lose));
     } catch (e) {
       return Promise.reject(e);
     }
@@ -7776,9 +7855,9 @@ var WSAPIMiniGames = /*#__PURE__*/function (_WSAPIRaffles) {
    * ```
    */
   ;
-  _proto.playMiniGameBatch = function playMiniGameBatch(template_id, spin_count, _temp5) {
-    var _ref4 = _temp5 === void 0 ? {} : _temp5,
-      onUpdate = _ref4.onUpdate;
+  _proto.playMiniGameBatch = function playMiniGameBatch(template_id, spin_count, _temp6) {
+    var _ref5 = _temp6 === void 0 ? {} : _temp6,
+      onUpdate = _ref5.onUpdate;
     try {
       var _this5 = this;
       if (typeof onUpdate === 'function') {
@@ -10813,6 +10892,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);
               });
             }
           });
@@ -10833,11 +10913,12 @@ var SmarticoAPI = /*#__PURE__*/function () {
       return Promise.reject(e);
     }
   };
-  _proto.doAcknowledgeRequest = function doAcknowledgeRequest(user_ext_id, request_id) {
+  _proto.doAcknowledgeRequest = function doAcknowledgeRequest(user_ext_id, request_id, lose) {
     try {
       var _this16 = this;
       var message = _this16.buildMessage(user_ext_id, exports.ClassId.SAW_AKNOWLEDGE_REQUEST, {
-        request_id: request_id
+        request_id: request_id,
+        lose: lose
       });
       return Promise.resolve(_this16.send(message, exports.ClassId.SAW_AKNOWLEDGE_RESPONSE));
     } catch (e) {