@smartico/public-api 0.0.409 → 0.0.410

package/dist/MiniGames/SAWDoAknowledgeRequest.d.ts

@@ -1,4 +1,6 @@
 import { ProtocolMessage } from '.././Base/ProtocolMessage';
 export interface SAWDoAknowledgeRequest extends ProtocolMessage {
     request_id: string;
+    /** When true, finalises the spin as lost: the prize is not credited and is returned to the prize pool. */
+    lose?: boolean;
 }

package/dist/MiniGames/SAWPrize.d.ts

@@ -9,14 +9,23 @@ export interface SAWPrize {
     place_from?: number;
     place_to?: number;
     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;
+    /** Initial (configured) stock. Present regardless of `expose_game_stat_on_api` */
     pool_initial?: number;
+    /** Times the prize has been won, across all players. Present only when `expose_game_stat_on_api` is enabled */
     wins_count?: number;
+    /** ISO weekday numbers (1 = Monday … 7 = Sunday) the prize can be won on; absent = any day. Present only when `expose_game_stat_on_api` is enabled */
     weekdays?: number[];
+    /** Prize availability window start (epoch ms), evaluated against `relative_period_timezone`. Present only when `expose_game_stat_on_api` is enabled */
     active_from_ts?: number;
+    /** Prize availability window end (epoch ms), evaluated against `relative_period_timezone`. Present only when `expose_game_stat_on_api` is enabled */
     active_till_ts?: number;
+    /** Timezone offset in minutes for `weekdays` / active-window evaluation (UTC minus local, as in JS `Date.getTimezoneOffset()`) */
     relative_period_timezone?: number;
+    /** When true, the prize stays winnable at `pool` 0 (unlimited stock) */
     is_surcharge?: boolean;
+    /** Always `false` in API responses — deleted prizes are excluded server-side */
     is_deleted?: boolean;
     prize_details_json?: {
         [key: string]: any;

package/dist/MiniGames/SAWTemplate.d.ts

@@ -32,6 +32,7 @@ export interface SAWTemplate {
         use_new_popups?: boolean;
         lottie_animation_speed?: number;
     };
+    /** 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;
     requires_prize_claim?: boolean;
     relative_period_timezone?: number;

package/dist/SmarticoAPI.d.ts

@@ -120,7 +120,7 @@ declare class SmarticoAPI {
     }): Promise<TGetJackpotEligibleGamesResponse>;
     sawGetTemplates(user_ext_id: string, force_language?: string, is_visitor_mode?: boolean): Promise<SAWGetTemplatesResponse>;
     sawGetTemplatesT(user_ext_id: string): Promise<TMiniGameTemplate[]>;
-    doAcknowledgeRequest(user_ext_id: string, request_id: string): Promise<SAWDoAknowledgeResponse>;
+    doAcknowledgeRequest(user_ext_id: string, request_id: string, lose?: boolean): Promise<SAWDoAknowledgeResponse>;
     sawSpinRequest(user_ext_id: string, saw_template_id: number, round_id?: number): Promise<SAWDoSpinResponse>;
     doAcknowledgeBatchRequest(user_ext_id: string, request_ids: string[]): Promise<SAWDoAcknowledgeBatchResponse>;
     sawSpinBatchRequest(user_ext_id: string, saw_template_id: number, spins_count: number): Promise<SAWDoSpinBatchResponse>;

package/dist/SmarticoLib/index.d.ts

@@ -2021,7 +2021,7 @@ declare class SmarticoAPI {
     coreCheckSegments(user_ext_id: string, segment_id: number[]): Promise<TSegmentCheckResult[]>;
     sawGetTemplates(user_ext_id: string, lang?: string, is_visitor_mode?: boolean): Promise<SAWGetTemplatesResponse>;
     sawGetTemplatesT(user_ext_id: string): Promise<TMiniGameTemplate[]>;
-    doAcknowledgeRequest(user_ext_id: string, request_id: string): Promise<SAWDoAknowledgeResponse>;
+    doAcknowledgeRequest(user_ext_id: string, request_id: string, lose?: boolean): Promise<SAWDoAknowledgeResponse>;
     sawSpinRequest(user_ext_id: string, saw_template_id: number, round_id?: number): Promise<SAWDoSpinResponse>;
     missionOptIn(user_ext_id: string, mission_id: number): Promise<AchievementOptinResponse>;
     missionClaimPrize(user_ext_id: string, mission_id: number, ach_completed_id: number): Promise<AchClaimPrizeResponse>;

package/dist/WSAPI/WSAPIJackpots.d.ts

@@ -297,7 +297,7 @@ export declare 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**
@@ -315,7 +315,12 @@ export declare 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).
      *
@@ -333,6 +338,10 @@ export declare 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);
      * ```
      */
     getJackpotEligibleGames({ jp_template_id, onUpdate }: {

package/dist/WSAPI/WSAPIMiniGames.d.ts

@@ -53,6 +53,27 @@ export declare 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.
      *
@@ -259,14 +280,19 @@ export declare 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
@@ -297,8 +323,10 @@ export declare 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).
@@ -363,18 +391,24 @@ export declare 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 });
      * }
      * ```
      */
@@ -384,9 +418,10 @@ export declare class WSAPIMiniGames extends WSAPIRaffles {
     }): Promise<TMiniGamePlayResult>;
     /**
      * 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.
      *
@@ -409,6 +444,23 @@ export declare 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. 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
@@ -423,11 +475,12 @@ export declare 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.
      *
      * **Visitor mode**: not supported.
@@ -437,6 +490,10 @@ export declare 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
@@ -447,6 +504,10 @@ export declare 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)) {
@@ -455,7 +516,9 @@ export declare class WSAPIMiniGames extends WSAPIRaffles {
      * }
      * ```
      */
-    miniGameWinAcknowledgeRequest(request_id: string): Promise<import("../MiniGames").SAWDoAknowledgeResponse>;
+    miniGameWinAcknowledgeRequest(request_id: string, { lose }?: {
+        lose?: boolean;
+    }): Promise<import("../MiniGames").SAWDoAknowledgeResponse>;
     /**
      * Plays a mini-game template `spin_count` times in one round-trip.
      * Returns an array of per-spin results — each independent, each

package/dist/WSAPI/WSAPITypes.d.ts

@@ -56,23 +56,23 @@ export interface TMiniGamePrize {
     second_btn_action_title?: string;
     /** Message when the prize pool is empty for that specific prize */
     out_of_stock_message?: string;
-    /** Number of items in stock */
+    /** 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?: number;
-    /** Initial number of items in stock */
+    /** Initial (configured) stock of the prize. Populated regardless of `expose_game_stat_on_api` */
     pool_initial?: number;
-    /** Number of wins in game */
+    /** Number of times the prize has been won, across all players. Populated only when the template's `expose_game_stat_on_api` is enabled */
     wins_count?: number;
-    /** Number of days of week, when the prize can be available */
+    /** ISO weekday numbers (1 = Monday … 7 = Sunday) on which the prize can be won; absent = any day. Populated only when the template's `expose_game_stat_on_api` is enabled */
     weekdays?: number[];
-    /** Holds time from which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp) */
+    /** Time from which the prize can be won (epoch ms), evaluated against `relative_period_timezone`. Populated only when the template's `expose_game_stat_on_api` is enabled */
     active_from_ts?: number;
-    /** Holds time till which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp) */
+    /** Time until which the prize can be won (epoch ms), evaluated against `relative_period_timezone`. Populated only when the template's `expose_game_stat_on_api` is enabled */
     active_till_ts?: number;
-    /** Time zone to ensure each day aligns with your local midnight. */
+    /** 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) */
     relative_period_timezone?: number;
-    /** Flag indicating that the prize is surcharged (available all the time, despite pool numbers) */
+    /** When true, the prize stays winnable even when its `pool` reaches 0 (effectively unlimited stock) */
     is_surcharge?: boolean;
-    /** Flag indicating the state of the prize */
+    /** 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 */
     custom_data?: any;
@@ -192,7 +192,7 @@ export interface TMiniGameTemplate {
     custom_data: any;
     /** List of prizes for mini-games */
     prizes: TMiniGamePrize[];
-    /** When enabled, the number of items in the pool and number of won items will be exposed in the Retention API and in the UI Widgets */
+    /** 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. */
     relative_period_timezone?: number;
@@ -202,7 +202,7 @@ export interface TMiniGameTemplate {
     activeTillDate?: number;
     /** The amount of steps to complete the game and gather the prize */
     steps_to_finish_game?: number;
-    /** Hold the id of the custom section */
+    /** 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 */
     saw_template_ui_definition: SAWTemplateUI;
@@ -214,7 +214,7 @@ export interface TMiniGameTemplate {
     max_number_of_attempts?: number;
     /** The period of time in milliseconds during which the user can do the maximum number of attempts */
     max_spins_period_ms?: number;
-    /** The ID of the user spin id to expose on the game */
+    /** 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 */
     expose_user_spin_id?: SAWExposeUserSpinIdName;
 }
 /**

package/dist/index.js

@@ -6369,7 +6369,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 +6387,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 +6410,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 +7220,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 +7468,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 +7511,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 +7579,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 +7634,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 +7660,23 @@ 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. 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,11 +7691,12 @@ 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.
    *
    * **Visitor mode**: not supported.
@@ -7644,6 +7706,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 +7720,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 +7733,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 +7848,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') {
@@ -10833,11 +10905,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) {