@smartico/public-api 0.0.408 → 0.0.410

package/dist/GamePick/GamePickTypes.d.ts

@@ -229,7 +229,12 @@ export interface GamePickEvent {
     resolution_score?: number;
     /** Whether this event is still accepting predictions */
     is_open_for_bets?: boolean;
-    /** Betting odds details for the event outcomes */
+    /** Per-outcome numbers keyed by the outcome value (`'1'` / `'x'` / `'2'`, `'yes'` / `'no'`, …).
+     * Dual-purpose by event type:
+     * - Sports / MatchX: decimal **betting odds** (e.g. `{ "1": 2.45, "x": 3.26, "2": 3.01 }`).
+     * - Quiz: when the round's `show_users_preference` is `true`, these are aggregated
+     *   **user-preference percentages** — what other users predicted, summing to ~100
+     *   (e.g. `{ "1": 33, "x": 25, "2": 42 }`). Render as the "what others predicted" bar. */
     odds_details?: {
         odd_value: {
             [key: string]: number;

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/Tournaments/GetClanTournamentPlayersResponse.d.ts

@@ -1,4 +1,5 @@
 import { ProtocolResponse } from '../Base/ProtocolResponse';
+import { TClanTournamentPlayers } from '../WSAPI/WSAPITypes';
 export interface ClanTournamentPlayerRaw {
     userId: number;
     cleanExtUserId: string;
@@ -16,19 +17,4 @@ export interface GetClanTournamentPlayersResponse extends ProtocolResponse {
     tournament_instance_id: number;
     players: ClanTournamentPlayerRaw[];
 }
-export interface TClanTournamentPlayer {
-    user_id: number;
-    clean_ext_user_id: string;
-    public_username: string;
-    avatar_id: string;
-    avatar_real_id: number;
-    avatar_url?: string;
-    position: number;
-    scores: number;
-    is_me: boolean;
-}
-export interface TClanTournamentPlayersResult {
-    tournament_instance_id: number;
-    players: TClanTournamentPlayer[];
-}
-export declare const clanTournamentPlayersTransform: (response: GetClanTournamentPlayersResponse) => TClanTournamentPlayersResult;
+export declare const clanTournamentPlayersTransform: (response: GetClanTournamentPlayersResponse) => TClanTournamentPlayers;

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

@@ -50,25 +50,29 @@ export interface TMiniGamePrize {
     acknowledge_dp_additional?: string;
     /** The name of the action button in modal pop-up (additional) */
     acknowledge_action_title_additional?: string;
+    /** Deep link that will trigger some action in modal pop-up (second button) */
+    second_btn?: string;
+    /** The name of the action button in modal pop-up (second button) */
+    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;
@@ -188,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;
@@ -198,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;
@@ -210,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;
 }
 /**