@smartico/public-api 0.0.432 → 0.0.433

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/package.json

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

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/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/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