@smartico/public-api 0.0.432 → 0.0.434

package/docs/api/README.md

@@ -123,6 +123,9 @@
 - [GetJackpotWinnersRequest](interfaces/GetJackpotWinnersRequest.md)
 - [GetJackpotWinnersResponse](interfaces/GetJackpotWinnersResponse.md)
 - [JackpotWinnerHistory](interfaces/JackpotWinnerHistory.md)
+- [JackpotWinStats](interfaces/JackpotWinStats.md)
+- [JackpotWin](interfaces/JackpotWin.md)
+- [TGetJackpotWinStatsResponse](interfaces/TGetJackpotWinStatsResponse.md)
 - [GetJackpotsPotsRequest](interfaces/GetJackpotsPotsRequest.md)
 - [GetJackpotsPotsResponse](interfaces/GetJackpotsPotsResponse.md)
 - [GetJackpotsRequest](interfaces/GetJackpotsRequest.md)

package/docs/api/classes/WSAPIJackpots.md

@@ -364,6 +364,106 @@ console.log('[smartico] render', winners.length, 'recent winner rows (amounts in
 
 ***
 
+### getJackpotWinStats()
+
+> **getJackpotWinStats**(`__namedParameters`): `Promise`\<[`TGetJackpotWinStatsResponse`](../interfaces/TGetJackpotWinStatsResponse.md)\>
+
+Returns past winners of a specific jackpot template, paginated, together
+with the win statistics of that template: total number of wins, the
+biggest win and the most recent win. Use it for a jackpot info modal /
+tooltip that shows "Total wins", "Highest win" and "Latest win" next to
+the winners list.
+
+#### Parameters
+
+##### \_\_namedParameters
+
+###### limit?
+
+`number`
+
+Page size of the winners list (default 20).
+
+###### offset?
+
+`number`
+
+Pagination offset of the winners list (default 0).
+
+###### jp_template_id?
+
+`number`
+
+Jackpot template ID (required).
+
+#### Returns
+
+`Promise`\<[`TGetJackpotWinStatsResponse`](../interfaces/TGetJackpotWinStatsResponse.md)\>
+
+[TGetJackpotWinStatsResponse](../interfaces/TGetJackpotWinStatsResponse.md) —
+`{ winners: JackpotWinnerHistory[], win_stats: JackpotWinStats }`.
+
+#### Remarks
+
+**Preconditions**
+- User must be authenticated. Visitor mode not supported.
+- `jp_template_id` is mandatory.
+- The consumer SHOULD check
+  `JackpotDetails.expose_winners_over_api` before calling, since
+  the server does not enforce it.
+
+**Statistics**
+- `win_stats` describes the whole jackpot template and does not depend
+  on `limit` / `offset`. Pass `limit: 1` when only the statistics are needed.
+- Only issued wins are counted — a pot that exploded but still waits for
+  manual approval is not included.
+- `highest_win` / `last_win` are `null` while the jackpot has no wins,
+  `total_wins` is `0` in that case.
+- `public_username` of `highest_win` / `last_win` is masked by the same
+  label setting as the winners list, and is `null` when the template
+  doesn't expose winners over API.
+- The server refreshes the statistics once per minute.
+
+**Currency caveat**
+All amounts (`win_stats.*.winning_amount`,
+`winners[].winner.winning_amount_jp_currency`) are in the jackpot's
+NATIVE currency, NOT the user's wallet currency.
+
+**Refresh**
+- The SDK caches each page separately (per `jp_template_id` +
+  `limit` + `offset`) for 30 seconds.
+- Caches clear on jackpot-win push events and on opt-in / opt-out.
+
+**Error handling**
+Non-zero `errCode` on control-group users or generic server errors. The
+SDK does NOT enumerate distinct codes — branch on `errCode === 0` and
+surface `errMsg` on failure.
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+const [jp] = await window._smartico.api.jackpotGet({ jp_template_id: 42 });
+
+if (!jp || !jp.expose_winners_over_api) {
+    console.log('[smartico] winners hidden by operator config — hide the stats');
+    return;
+}
+
+const { winners, win_stats } = await window._smartico.api.getJackpotWinStats({
+    jp_template_id: 42,
+    limit:          10,
+    offset:         0,
+});
+console.log('[smartico] total wins', win_stats.total_wins);
+console.log('[smartico] highest win', win_stats.highest_win?.winning_amount, jp.jp_currency);
+console.log('[smartico] latest win', win_stats.last_win?.public_username, win_stats.last_win?.win_date_ts);
+console.log('[smartico] render', winners.length, 'recent winner rows');
+```
+
+***
+
 ### getJackpotEligibleGames()
 
 > **getJackpotEligibleGames**(`__namedParameters`): `Promise`\<[`TGetJackpotEligibleGamesResponse`](../interfaces/TGetJackpotEligibleGamesResponse.md)\>

package/docs/api/interfaces/GetJackpotWinnersResponse.md

@@ -69,3 +69,11 @@ The list of jackpot winners
 > **has\_more**: `boolean`
 
 Whether there are more winners to fetch
+
+***
+
+### win\_stats?
+
+> `optional` **win\_stats?**: [`JackpotWinStats`](JackpotWinStats.md)
+
+Win statistics of the jackpot template

package/docs/api/interfaces/JackpotWin.md

@@ -0,0 +1,25 @@
+# Interface: JackpotWin
+
+## Properties
+
+### winning\_amount
+
+> **winning\_amount**: `number`
+
+Won amount in the Jackpot currency
+
+***
+
+### win\_date\_ts
+
+> **win\_date\_ts**: `number`
+
+Date of winning in milliseconds
+
+***
+
+### public\_username
+
+> **public\_username**: `string`
+
+Name of the winner, masked by default. `null` when the jackpot template doesn't expose winners over API

package/docs/api/interfaces/JackpotWinStats.md

@@ -0,0 +1,25 @@
+# Interface: JackpotWinStats
+
+## Properties
+
+### total\_wins
+
+> **total\_wins**: `number`
+
+Total number of issued wins of the jackpot template. Wins waiting for manual approval are not counted
+
+***
+
+### highest\_win
+
+> **highest\_win**: [`JackpotWin`](JackpotWin.md)
+
+The biggest win of the jackpot template, `null` when there are no wins yet
+
+***
+
+### last\_win
+
+> **last\_win**: [`JackpotWin`](JackpotWin.md)
+
+The most recent win of the jackpot template, `null` when there are no wins yet

package/docs/api/interfaces/TGetJackpotWinStatsResponse.md

@@ -0,0 +1,17 @@
+# Interface: TGetJackpotWinStatsResponse
+
+## Properties
+
+### winners
+
+> **winners**: [`JackpotWinnerHistory`](JackpotWinnerHistory.md)[]
+
+The list of jackpot winners
+
+***
+
+### win\_stats
+
+> **win\_stats**: [`JackpotWinStats`](JackpotWinStats.md)
+
+Win statistics of the jackpot template

package/docs/capabilities/getJackpotWinStats.md

@@ -0,0 +1,111 @@
+# getJackpotWinStats — API (TGetJackpotWinStatsResponse)
+
+> Returns past winners of a specific jackpot template, paginated, together with the win statistics of that template: total number of wins, the biggest win and the most recent win.
+> Import: `import { TGetJackpotWinStatsResponse } from '@smartico/public-api'`
+> Search terms: getJackpotWinStats, jackpots, TGetJackpotWinStatsResponse, JackpotWinnerHistory, JackPotWinner, JackpotWinStats, JackpotWin
+
+## Signature
+```ts
+_smartico.api.getJackpotWinStats({
+		limit,
+		offset,
+		jp_template_id,
+	}: {
+		/** Page size of the winners list (default 20). */
+		limit?: number;
+		/** Pagination offset of the winners list (default 0). */
+		offset?: number;
+		/** Jackpot template ID (required). */
+		jp_template_id?: number;
+	}): Promise<TGetJackpotWinStatsResponse>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TGetJackpotWinStatsResponse>`
+`TGetJackpotWinStatsResponse`:
+- `winners` (JackpotWinnerHistory[]) — The list of jackpot winners
+  - `jp_pot_id` (number) — Id of the jackpot pot
+  - `win_date_ts` (number) — Date of winning in milliseconds
+  - `winner` (JackPotWinner) — Info about jackpot winner
+    - `is_me` (boolean) — Flag indicating that this winner is the currently logged in user
+    - `public_username` (string) — Name of the winner, note that for all users except is_me, the name is masked by default, but masking can be disabled by request to Smartico AM team
+    - `winning_amount_jp_currency` (number) — Won amount in the Jackpot currency
+    - `winning_amount_wallet_currency` (number) — Won amount in the user Wallet currency
+    - `winning_position` (number) — Position of the winner. Relevant for jackpots where there could be multiple winners
+    - `avatar_id` (string) — Avatar image URL of the winner
+    - `avatar_real_id` (number | null) — Numeric ID of the winner's avatar; `null` when the winner has not picked one
+- `win_stats` (JackpotWinStats) — Win statistics of the jackpot template
+  - `total_wins` (number) — Total number of issued wins of the jackpot template. Wins waiting for manual approval are not counted
+  - `highest_win` (JackpotWin | null) — The biggest win of the jackpot template, `null` when there are no wins yet
+    - `winning_amount` (number) — Won amount in the Jackpot currency
+    - `win_date_ts` (number) — Date of winning in milliseconds
+    - `public_username` (string | null) — Name of the winner, masked by default. `null` when the jackpot template doesn't expose winners over API
+  - `last_win` (JackpotWin | null) — The most recent win of the jackpot template, `null` when there are no wins yet
+    - `winning_amount` (number) — Won amount in the Jackpot currency
+    - `win_date_ts` (number) — Date of winning in milliseconds
+    - `public_username` (string | null) — Name of the winner, masked by default. `null` when the jackpot template doesn't expose winners over API
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode not supported.
+- `jp_template_id` is mandatory.
+- The consumer SHOULD check
+  `JackpotDetails.expose_winners_over_api` before calling, since
+  the server does not enforce it.
+
+**Statistics**
+- `win_stats` describes the whole jackpot template and does not depend
+  on `limit` / `offset`. Pass `limit: 1` when only the statistics are needed.
+- Only issued wins are counted — a pot that exploded but still waits for
+  manual approval is not included.
+- `highest_win` / `last_win` are `null` while the jackpot has no wins,
+  `total_wins` is `0` in that case.
+- `public_username` of `highest_win` / `last_win` is masked by the same
+  label setting as the winners list, and is `null` when the template
+  doesn't expose winners over API.
+- The server refreshes the statistics once per minute.
+
+**Currency caveat**
+All amounts (`win_stats.*.winning_amount`,
+`winners[].winner.winning_amount_jp_currency`) are in the jackpot's
+NATIVE currency, NOT the user's wallet currency.
+
+**Refresh**
+- The SDK caches each page separately (per `jp_template_id` +
+  `limit` + `offset`) for 30 seconds.
+- Caches clear on jackpot-win push events and on opt-in / opt-out.
+
+**Error handling**
+Non-zero `errCode` on control-group users or generic server errors. The
+SDK does NOT enumerate distinct codes — branch on `errCode === 0` and
+surface `errMsg` on failure.
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const [jp] = await window._smartico.api.jackpotGet({ jp_template_id: 42 });
+
+if (!jp || !jp.expose_winners_over_api) {
+    console.log('[smartico] winners hidden by operator config — hide the stats');
+    return;
+}
+
+const { winners, win_stats } = await window._smartico.api.getJackpotWinStats({
+    jp_template_id: 42,
+    limit:          10,
+    offset:         0,
+});
+console.log('[smartico] total wins', win_stats.total_wins);
+console.log('[smartico] highest win', win_stats.highest_win?.winning_amount, jp.jp_currency);
+console.log('[smartico] latest win', win_stats.last_win?.public_username, win_stats.last_win?.win_date_ts);
+console.log('[smartico] render', winners.length, 'recent winner rows');
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `TGetJackpotWinStatsResponse`

package/docs/ui/inbox/UIGuide_getInboxMessageBody.md

@@ -2,8 +2,9 @@
 
 ## Overview
 - Returns the rich body (title, preview, icon, action, html_body,
-  buttons, custom_data) for one message identified by its
-  `message_guid`.
+  buttons, custom_data) and the preview-popup settings
+  (`show_preview`, `show_duration_sec`) for one message identified
+  by its `message_guid`.
 - Fetched from a CDN, NOT over the WebSocket — latency depends on
   CDN proximity. No SDK-level cache (browser HTTP cache may apply
   via CDN Cache-Control headers).
@@ -42,6 +43,27 @@ payload has `html_body` or `buttons` but the action isn't
 consumer. Don't try to render `html_body` for non-`'dp:inbox'`
 messages — it will be `undefined`.
 
+## Preview popup vs silent delivery
+
+Every message is stored in the inbox list. The preview settings
+decide whether a newly arrived message also pops up briefly (the
+"toast" the default Smartico UI shows while the user is online).
+
+| Field | Value | Behaviour |
+|---|---|---|
+| `show_preview` | `true` or missing | Show a preview popup and store the message in the list |
+| `show_preview` | `false` | Store the message silently, with no popup |
+| `show_duration_sec` | number | Hide the popup after this many seconds |
+| `show_duration_sec` | `null` or missing | Hide the popup after 7 seconds (the default Smartico UI's default) |
+
+Values are returned exactly as the operator configured them, so
+apply the defaults above yourself (e.g. `body.show_preview !== false`,
+`body.show_duration_sec ?? 7`).
+
+Only show the popup for messages that arrive while the user is
+online. Messages loaded from history via {@link getInboxMessages}
+should go straight into the list.
+
 ## Sandboxed iframe (for `html_body`)
 
 `html_body` is operator-supplied HTML. **Render in a sandboxed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smartico/public-api",
-	"version": "0.0.432",
+	"version": "0.0.434",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/src/Inbox/InboxMessage.ts

@@ -23,7 +23,7 @@ export interface InboxMessageBody {
 	// default is 'true'
 	show_preview?: boolean;
 	// duration in seconds for how long to show preview, default is 7 seconds
-	show_duration_sec?: number;
+	show_duration_sec?: number | null;
 	// indicator if the image in html_body can be zoomed out
 	// default is 'false'
 	enable_zoom_mode?: boolean;
@@ -62,6 +62,8 @@ export const InboxMessageBodyTransform = (item: InboxMessageBody): TInboxMessage
 		title: item.title,
 		preview_body: item.body,
 		custom_data: IntUtils.JsonOrText(item?.custom_data),
+		show_preview: item.show_preview,
+		show_duration_sec: item.show_duration_sec,
 	};
 
 	if (item.action === 'dp:inbox') {

package/src/Jackpots/GetJackpotWinnersResponse.ts

@@ -6,6 +6,8 @@ export interface GetJackpotWinnersResponse extends ProtocolResponse {
 	winners: JackpotWinnerHistory[];
 	/** Whether there are more winners to fetch */
 	has_more: boolean;
+	/** Win statistics of the jackpot template */
+	win_stats?: JackpotWinStats;
 }
 
 export interface JackpotWinnerHistory {
@@ -17,6 +19,31 @@ export interface JackpotWinnerHistory {
 	winner: JackPotWinner;
 }
 
+export interface JackpotWinStats {
+	/** Total number of issued wins of the jackpot template. Wins waiting for manual approval are not counted */
+	total_wins: number;
+	/** The biggest win of the jackpot template, `null` when there are no wins yet */
+	highest_win: JackpotWin | null;
+	/** The most recent win of the jackpot template, `null` when there are no wins yet */
+	last_win: JackpotWin | null;
+}
+
+export interface JackpotWin {
+	/** Won amount in the Jackpot currency */
+	winning_amount: number;
+	/** Date of winning in milliseconds */
+	win_date_ts: number;
+	/** Name of the winner, masked by default. `null` when the jackpot template doesn't expose winners over API */
+	public_username: string | null;
+}
+
+export interface TGetJackpotWinStatsResponse {
+	/** The list of jackpot winners */
+	winners: JackpotWinnerHistory[];
+	/** Win statistics of the jackpot template */
+	win_stats: JackpotWinStats;
+}
+
 /**
  * @ignore
  */
@@ -31,3 +58,17 @@ export const GetJackpotWinnersResponseTransform = (items: JackpotWinnerHistory[]
 		return winnerInfo;
 	});
 };
+
+/**
+ * @ignore
+ */
+export const GetJackpotWinStatsResponseTransform = (response: GetJackpotWinnersResponse): TGetJackpotWinStatsResponse => {
+	return {
+		winners: GetJackpotWinnersResponseTransform(response.winners ?? []),
+		win_stats: {
+			total_wins: response.win_stats?.total_wins ?? 0,
+			highest_win: response.win_stats?.highest_win ?? null,
+			last_win: response.win_stats?.last_win ?? null,
+		},
+	};
+};

package/src/MiniGames/SAWTemplateUI.ts

@@ -486,6 +486,35 @@ export interface SAWTemplateUI {
      */
     use_custom?: boolean;
 
+    /**
+     * Whether a custom mini-game fills the whole mini-game window instead of
+     * the default fixed-size frame (800×516 on desktop, 400×745 on mobile).
+     *
+     * Applies wherever the game is opened — a spin attempt shown to the user,
+     * a deep link, or `_smartico.miniGame()` in standalone or inline mode.
+     * The `fullscreen` option of `_smartico.miniGame()` overrides it per call.
+     *
+     * When `false` or omitted, the default frame size is used.
+     * Back-Office label: _"Standalone full screen"_.
+     */
+    standalone_fullscreen?: boolean;
+
+    /**
+     * Width of the custom mini-game frame on desktop when opened standalone or inline,
+     * as a CSS size (`800px`, `100%`, `90vw`; a bare number is treated as pixels).
+     * Empty or invalid values fall back to the default 800px. Ignored on mobile.
+     * Back-Office label: _"Standalone width"_.
+     */
+    standalone_width?: string;
+
+    /**
+     * Height of the custom mini-game frame on desktop when opened standalone or inline,
+     * as a CSS size (`516px`, `100%`, `90vh`; a bare number is treated as pixels).
+     * Empty or invalid values fall back to the default 516px. Ignored on mobile.
+     * Back-Office label: _"Standalone height"_.
+     */
+    standalone_height?: string;
+
 	/**
 	 * Minutes for the Voyager seed window.
 	 * The seed window is the range of seeds that can be used to generate the map.

package/src/SmarticoAPI.ts

@@ -146,7 +146,13 @@ import { GetAvatarsCustomizedResponse, avatarCustomizedTransform } from './Avata
 import { GetAvatarPromptsResponse, avatarPromptTransform } from './Avatars/GetAvatarPromptsResponse';
 import { SetAvatarRequest, SetAvatarResponse } from './Avatars';
 import { AvatarCustomizeResponse } from './Avatars/AvatarCustomizeResponse';
-import { GetJackpotWinnersResponse, GetJackpotWinnersResponseTransform, JackpotWinnerHistory } from './Jackpots/GetJackpotWinnersResponse';
+import {
+	GetJackpotWinnersResponse,
+	GetJackpotWinnersResponseTransform,
+	GetJackpotWinStatsResponseTransform,
+	JackpotWinnerHistory,
+	TGetJackpotWinStatsResponse,
+} from './Jackpots/GetJackpotWinnersResponse';
 import { GetJackpotWinnersRequest } from './Jackpots/GetJackpotWinnersRequest';
 import { GetJackpotEligibleGamesRequest } from './Jackpots/GetJackpotEligibleGamesRequest';
 import { GetJackpotEligibleGamesResponse, GetJackpotEligibleGamesResponseTransform, JackpotEligibleGame, TGetJackpotEligibleGamesResponse } from './Jackpots/GetJackpotEligibleGamesResponse';
@@ -611,6 +617,10 @@ class SmarticoAPI {
 		return GetJackpotWinnersResponseTransform((await this.getJackpotWinners(user_ext_id, limit, offset, jp_template_id)).winners);
 	}
 
+	public async getJackpotWinStatsT(user_ext_id: string, limit: number = 20, offset: number = 0, jp_template_id: number): Promise<TGetJackpotWinStatsResponse> {
+		return GetJackpotWinStatsResponseTransform(await this.getJackpotWinners(user_ext_id, limit, offset, jp_template_id));
+	}
+
 	public async getJackpotEligibleGames(user_ext_id: string, { jp_template_id }: { jp_template_id: number }): Promise<GetJackpotEligibleGamesResponse> {
 		const message = this.buildMessage<GetJackpotEligibleGamesRequest, GetJackpotEligibleGamesResponse>(
 			user_ext_id,

package/src/SmarticoGlobal.ts

@@ -50,6 +50,24 @@ export interface SmarticoWidgetParams {
 	zoom?: number;
 	/** Force the mobile layout regardless of viewport. */
 	force_mobile?: boolean;
+	/**
+	 * Custom mini-games only ({@link SmarticoGlobal.miniGame}): `true` fills the whole mini-game window,
+	 * `false` keeps the default fixed-size frame. Overrides the template's "Standalone full screen" setting;
+	 * when omitted, the template setting is used.
+	 */
+	fullscreen?: boolean;
+	/**
+	 * Custom mini-games only ({@link SmarticoGlobal.miniGame}): desktop width of the game frame as a CSS size
+	 * (`1000px`, `100%`, `90vw`; a number is treated as pixels). Overrides the template's "Standalone width"
+	 * and "Standalone full screen" settings. Ignored on mobile.
+	 */
+	frame_width?: string | number;
+	/**
+	 * Custom mini-games only ({@link SmarticoGlobal.miniGame}): desktop height of the game frame as a CSS size
+	 * (`600px`, `100%`, `90vh`; a number is treated as pixels). Overrides the template's "Standalone height"
+	 * and "Standalone full screen" settings. Ignored on mobile.
+	 */
+	frame_height?: string | number;
 }
 
 /**

package/src/WSAPI/WSAPIInbox.ts

@@ -363,6 +363,16 @@ export class WSAPIInbox extends WSAPILeaderBoard {
 	 * for safe execution — that helper handles URL vs deep-link
 	 * routing.
 	 *
+	 * **Preview vs silent delivery**
+	 * Every message belongs in your inbox list. `show_preview` decides
+	 * whether it should also pop up briefly when it arrives:
+	 * - `show_preview !== false` → show a preview popup for
+	 *   `show_duration_sec ?? 7` seconds.
+	 * - `show_preview === false` → store it silently, with no popup.
+	 * These fields are returned exactly as the operator configured them;
+	 * a missing value means the default above, the same as the default
+	 * Smartico UI.
+	 *
 	 * **Idempotency / Side effects**: safe. Read-only HTTP fetch.
 	 *
 	 * **UI guidance**: see [UI Guide — `getInboxMessageBody`](../../docs/ui/inbox/UIGuide_getInboxMessageBody.md).
@@ -388,6 +398,12 @@ export class WSAPIInbox extends WSAPILeaderBoard {
 	 *   console.log('[smartico] simple message — show preview_body + single CTA wired to:', body.action,
 	 *     '— execute via _smartico.dp(body.action)');
 	 * }
+	 *
+	 * if (body.show_preview !== false) {
+	 *   console.log('[smartico] new message — show a preview popup for', body.show_duration_sec ?? 7, 'seconds');
+	 * } else {
+	 *   console.log('[smartico] new message — store it in the inbox silently, no popup');
+	 * }
 	 * ```
 	 */
 	public async getInboxMessageBody(messageGuid: string): Promise<TInboxMessageBody> {

package/src/WSAPI/WSAPIJackpots.ts

@@ -8,6 +8,7 @@ import {
 } from '../Jackpots';
 import { IntUtils } from '../IntUtils';
 import { TGetJackpotEligibleGamesResponse } from '../Jackpots/GetJackpotEligibleGamesResponse';
+import { TGetJackpotWinStatsResponse } from '../Jackpots/GetJackpotWinnersResponse';
 import {
 	JACKPOT_TEMPLATE_CACHE_SEC,
 	JACKPOT_POT_CACHE_SEC,
@@ -390,6 +391,94 @@ export class WSAPIJackpots extends WSAPIClans {
 		);
 	}
 
+	/**
+	 * Returns past winners of a specific jackpot template, paginated, together
+	 * with the win statistics of that template: total number of wins, the
+	 * biggest win and the most recent win. Use it for a jackpot info modal /
+	 * tooltip that shows "Total wins", "Highest win" and "Latest win" next to
+	 * the winners list.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 * - `jp_template_id` is mandatory.
+	 * - The consumer SHOULD check
+	 *   `JackpotDetails.expose_winners_over_api` before calling, since
+	 *   the server does not enforce it.
+	 *
+	 * **Statistics**
+	 * - `win_stats` describes the whole jackpot template and does not depend
+	 *   on `limit` / `offset`. Pass `limit: 1` when only the statistics are needed.
+	 * - Only issued wins are counted — a pot that exploded but still waits for
+	 *   manual approval is not included.
+	 * - `highest_win` / `last_win` are `null` while the jackpot has no wins,
+	 *   `total_wins` is `0` in that case.
+	 * - `public_username` of `highest_win` / `last_win` is masked by the same
+	 *   label setting as the winners list, and is `null` when the template
+	 *   doesn't expose winners over API.
+	 * - The server refreshes the statistics once per minute.
+	 *
+	 * **Currency caveat**
+	 * All amounts (`win_stats.*.winning_amount`,
+	 * `winners[].winner.winning_amount_jp_currency`) are in the jackpot's
+	 * NATIVE currency, NOT the user's wallet currency.
+	 *
+	 * **Refresh**
+	 * - The SDK caches each page separately (per `jp_template_id` +
+	 *   `limit` + `offset`) for 30 seconds.
+	 * - Caches clear on jackpot-win push events and on opt-in / opt-out.
+	 *
+	 * **Error handling**
+	 * Non-zero `errCode` on control-group users or generic server errors. The
+	 * SDK does NOT enumerate distinct codes — branch on `errCode === 0` and
+	 * surface `errMsg` on failure.
+	 *
+	 * **Visitor mode**: not supported.
+	 *
+	 * @returns {@link TGetJackpotWinStatsResponse} —
+	 * `{ winners: JackpotWinnerHistory[], win_stats: JackpotWinStats }`.
+	 *
+	 * @example
+	 * ```ts
+	 * const [jp] = await window._smartico.api.jackpotGet({ jp_template_id: 42 });
+	 *
+	 * if (!jp || !jp.expose_winners_over_api) {
+	 *     console.log('[smartico] winners hidden by operator config — hide the stats');
+	 *     return;
+	 * }
+	 *
+	 * const { winners, win_stats } = await window._smartico.api.getJackpotWinStats({
+	 *     jp_template_id: 42,
+	 *     limit:          10,
+	 *     offset:         0,
+	 * });
+	 * console.log('[smartico] total wins', win_stats.total_wins);
+	 * console.log('[smartico] highest win', win_stats.highest_win?.winning_amount, jp.jp_currency);
+	 * console.log('[smartico] latest win', win_stats.last_win?.public_username, win_stats.last_win?.win_date_ts);
+	 * console.log('[smartico] render', winners.length, 'recent winner rows');
+	 * ```
+	 */
+	public async getJackpotWinStats({
+		limit,
+		offset,
+		jp_template_id,
+	}: {
+		/** Page size of the winners list (default 20). */
+		limit?: number;
+		/** Pagination offset of the winners list (default 0). */
+		offset?: number;
+		/** Jackpot template ID (required). */
+		jp_template_id?: number;
+	}): Promise<TGetJackpotWinStatsResponse> {
+		const cacheKey = `${onUpdateContextKey.JackpotWinners}stats:${jp_template_id}:${limit}:${offset}`;
+		return OCache.use(
+			cacheKey,
+			ECacheContext.WSAPI,
+			() => this.api.getJackpotWinStatsT(this.userExtId, limit, offset, jp_template_id),
+			JACKPOT_WINNERS_CACHE_SEC,
+		);
+	}
+
 	/**
 	 * Returns the casino games eligible to contribute to a specific jackpot —
 	 * the catalog the user must play to grow the pot. Use to power an

package/src/WSAPI/WSAPITypes.ts

@@ -1146,6 +1146,12 @@ export interface TInboxMessageBody {
 	/** Operator-defined custom data. The SDK auto-parses JSON-looking
 	 * strings, so at runtime this is `any` despite the `string` type. */
 	custom_data?: string;
+	/** Whether to show a short preview popup when the message arrives.
+	 * `false` means store it in the inbox silently; missing means `true`. */
+	show_preview?: boolean;
+	/** How long the preview popup stays visible, in seconds.
+	 * `null` or missing means 7 seconds. */
+	show_duration_sec?: number | null;
 }
 
 /**