@smartico/public-api 0.0.380 → 0.0.382

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (178) hide show
  1. package/CLAUDE.md +103 -0
  2. package/README.md +32 -10
  3. package/dist/Base/ClassId.d.ts +2 -0
  4. package/dist/Jackpots/JackpotDetails.d.ts +14 -15
  5. package/dist/Jackpots/JackpotPot.d.ts +10 -6
  6. package/dist/MiniGames/SAWGameType.d.ts +3 -1
  7. package/dist/MiniGames/SAWTemplateUI.d.ts +7 -0
  8. package/dist/Raffle/GetRaffleWonPrizesRequest.d.ts +9 -0
  9. package/dist/Raffle/GetRaffleWonPrizesResponse.d.ts +52 -0
  10. package/dist/Raffle/index.d.ts +2 -0
  11. package/dist/SmarticoAPI.d.ts +6 -1
  12. package/dist/SmarticoLib/index.d.ts +5 -1
  13. package/dist/WSAPI/WSAPIAvatars.d.ts +267 -49
  14. package/dist/WSAPI/WSAPIBonuses.d.ts +224 -10
  15. package/dist/WSAPI/WSAPIGamePick.d.ts +538 -253
  16. package/dist/WSAPI/WSAPIGeneral.d.ts +156 -14
  17. package/dist/WSAPI/WSAPIInbox.d.ts +547 -58
  18. package/dist/WSAPI/WSAPIJackpots.d.ts +292 -57
  19. package/dist/WSAPI/WSAPILeaderBoard.d.ts +127 -13
  20. package/dist/WSAPI/WSAPIMiniGames.d.ts +465 -49
  21. package/dist/WSAPI/WSAPIRaffles.d.ts +576 -52
  22. package/dist/WSAPI/WSAPITournaments.d.ts +3 -3
  23. package/dist/WSAPI/WSAPITypes.d.ts +243 -132
  24. package/dist/WSAPI/WSAPIUser.d.ts +193 -43
  25. package/dist/index.js +3412 -616
  26. package/dist/index.js.map +1 -1
  27. package/dist/index.modern.mjs +3395 -609
  28. package/dist/index.modern.mjs.map +1 -1
  29. package/docs/Callbacks.md +162 -0
  30. package/docs/SmarticoObject.md +445 -0
  31. package/docs/Transforms.md +99 -0
  32. package/docs/api/README.md +26 -0
  33. package/docs/api/classes/WSAPIAvatars.md +282 -54
  34. package/docs/api/classes/WSAPIBonuses.md +233 -12
  35. package/docs/api/classes/WSAPIClans.md +380 -10
  36. package/docs/api/classes/WSAPIGamePick.md +555 -26
  37. package/docs/api/classes/WSAPIGeneral.md +165 -16
  38. package/docs/api/classes/WSAPIInbox.md +588 -64
  39. package/docs/api/classes/WSAPIJackpots.md +320 -66
  40. package/docs/api/classes/WSAPILeaderBoard.md +133 -15
  41. package/docs/api/classes/WSAPIMiniGames.md +501 -64
  42. package/docs/api/classes/WSAPIMissions.md +58 -79
  43. package/docs/api/classes/WSAPIRaffles.md +647 -69
  44. package/docs/api/classes/WSAPIStore.md +83 -108
  45. package/docs/api/classes/WSAPITournaments.md +495 -28
  46. package/docs/api/classes/WSAPIUser.md +520 -83
  47. package/docs/api/documents/Callbacks.md +162 -0
  48. package/docs/api/documents/SmarticoObject.md +445 -0
  49. package/docs/api/documents/Transforms.md +99 -0
  50. package/docs/api/enumerations/BonusStatus-1.md +11 -6
  51. package/docs/api/enumerations/JoinClanErrorCode.md +81 -0
  52. package/docs/api/enumerations/TournamentRegistrationError.md +12 -0
  53. package/docs/api/functions/clanTournamentPlayersTransform.md +13 -0
  54. package/docs/api/interfaces/AvatarCustomized.md +25 -0
  55. package/docs/api/interfaces/AvatarDefinition.md +94 -0
  56. package/docs/api/interfaces/AvatarPrompt.md +45 -0
  57. package/docs/api/interfaces/BonusMetaMap-1.md +4 -1
  58. package/docs/api/interfaces/BonusTemplateMetaMap-1.md +9 -4
  59. package/docs/api/interfaces/Clan.md +4 -0
  60. package/docs/api/interfaces/ClanInfo.md +109 -0
  61. package/docs/api/interfaces/ClanMember.md +53 -0
  62. package/docs/api/interfaces/ClanTournamentPlayerRaw.md +67 -0
  63. package/docs/api/interfaces/GemsDiamondsLog.md +43 -0
  64. package/docs/api/interfaces/GetClanInfoResponse.md +61 -0
  65. package/docs/api/interfaces/GetClanTournamentPlayersResponse.md +81 -0
  66. package/docs/api/interfaces/GetRaffleWonPrizesRequest.md +59 -0
  67. package/docs/api/interfaces/GetRaffleWonPrizesResponse.md +95 -0
  68. package/docs/api/interfaces/InboxMarkMessageAction.md +10 -2
  69. package/docs/api/interfaces/JackpotDetails.md +14 -15
  70. package/docs/api/interfaces/JackpotPot.md +9 -6
  71. package/docs/api/interfaces/LeaderBoardDetailsT.md +14 -8
  72. package/docs/api/interfaces/LeaderBoardUserT.md +8 -5
  73. package/docs/api/interfaces/LeaderBoardsRewardsT.md +7 -0
  74. package/docs/api/interfaces/PointsLog.md +43 -0
  75. package/docs/api/interfaces/RaffleWonPrize.md +59 -0
  76. package/docs/api/interfaces/RaffleWonPrizePublicMeta.md +27 -0
  77. package/docs/api/interfaces/RaffleWonPrizeUser.md +43 -0
  78. package/docs/api/interfaces/TAchCategory.md +2 -7
  79. package/docs/api/interfaces/TAvatarCustomized.md +4 -4
  80. package/docs/api/interfaces/TAvatarDefinition.md +13 -14
  81. package/docs/api/interfaces/TAvatarPrompt.md +6 -6
  82. package/docs/api/interfaces/TBonus.md +16 -8
  83. package/docs/api/interfaces/TBuyStoreItemResult.md +4 -29
  84. package/docs/api/interfaces/TClaimBonusResult.md +5 -5
  85. package/docs/api/interfaces/TClan.md +8 -4
  86. package/docs/api/interfaces/TClanInfo.md +47 -0
  87. package/docs/api/interfaces/TClanJoinResult.md +11 -1
  88. package/docs/api/interfaces/TClanTournamentPlayer.md +55 -0
  89. package/docs/api/interfaces/TClanTournamentPlayersResult.md +27 -0
  90. package/docs/api/interfaces/TClans.md +3 -1
  91. package/docs/api/interfaces/TGetTranslations.md +4 -0
  92. package/docs/api/interfaces/TInboxMessage.md +14 -6
  93. package/docs/api/interfaces/TInboxMessageBody.md +18 -12
  94. package/docs/api/interfaces/TLevel.md +17 -20
  95. package/docs/api/interfaces/TLevelCurrent.md +19 -18
  96. package/docs/api/interfaces/TMiniGamePlayBatchResult.md +14 -6
  97. package/docs/api/interfaces/TMiniGamePlayResult.md +9 -4
  98. package/docs/api/interfaces/TMissionClaimRewardResult.md +1 -9
  99. package/docs/api/interfaces/TMissionOptInResult.md +1 -5
  100. package/docs/api/interfaces/TMissionOrBadge.md +4 -7
  101. package/docs/api/interfaces/TRaffleOptinResponse.md +4 -2
  102. package/docs/api/interfaces/TSegmentCheckResult.md +10 -0
  103. package/docs/api/interfaces/TSetAvatarResult.md +3 -3
  104. package/docs/api/interfaces/TStoreItem.md +3 -13
  105. package/docs/api/interfaces/TTournament.md +1 -1
  106. package/docs/api/interfaces/TTournamentDetailed.md +1 -1
  107. package/docs/api/interfaces/TTournamentRegistrationResult.md +4 -2
  108. package/docs/api/interfaces/TUICustomSection.md +23 -19
  109. package/docs/api/interfaces/TUserProfile.md +18 -16
  110. package/docs/api/interfaces/TransformedRaffleClaimPrizeResponse.md +6 -2
  111. package/docs/api/interfaces/UserLevelExtraCountersT.md +9 -2
  112. package/docs/api/type-aliases/ActivityLogEntry.md +3 -0
  113. package/docs/native/ADDING_METHODS.md +7 -2
  114. package/docs/native/PROTOCOL.md +337 -0
  115. package/docs/ui/avatars/UIGuide_getAvatarPrompts.md +100 -0
  116. package/docs/ui/avatars/UIGuide_getAvatarsCustomized.md +90 -0
  117. package/docs/ui/avatars/UIGuide_getAvatarsList.md +105 -0
  118. package/docs/ui/avatars/UIGuide_setAvatar.md +118 -0
  119. package/docs/ui/bonuses/UIGuide_claimBonus.md +144 -0
  120. package/docs/ui/bonuses/UIGuide_getBonuses.md +176 -0
  121. package/docs/ui/gamepick/UIGuide_gamePickGetActiveRound.md +99 -0
  122. package/docs/ui/gamepick/UIGuide_gamePickGetActiveRounds.md +76 -0
  123. package/docs/ui/gamepick/UIGuide_gamePickGetBoard.md +81 -0
  124. package/docs/ui/gamepick/UIGuide_gamePickGetGameInfo.md +78 -0
  125. package/docs/ui/gamepick/UIGuide_gamePickGetHistory.md +55 -0
  126. package/docs/ui/gamepick/UIGuide_gamePickGetRoundInfoForUser.md +71 -0
  127. package/docs/ui/gamepick/UIGuide_gamePickGetUserInfo.md +64 -0
  128. package/docs/ui/gamepick/UIGuide_gamePickSubmitSelection.md +103 -0
  129. package/docs/ui/gamepick/UIGuide_gamePickSubmitSelectionQuiz.md +67 -0
  130. package/docs/ui/general/UIGuide_getCustomSections.md +137 -0
  131. package/docs/ui/general/UIGuide_getRelatedItemsForGame.md +140 -0
  132. package/docs/ui/inbox/UIGuide_deleteInboxMessage.md +135 -0
  133. package/docs/ui/inbox/UIGuide_getInboxMessageBody.md +133 -0
  134. package/docs/ui/inbox/UIGuide_getInboxMessages.md +186 -0
  135. package/docs/ui/inbox/UIGuide_markInboxMessageAsRead.md +122 -0
  136. package/docs/ui/inbox/UIGuide_markUnmarkInboxMessageAsFavorite.md +84 -0
  137. package/docs/ui/jackpots/UIGuide_getJackpotEligibleGames.md +73 -0
  138. package/docs/ui/jackpots/UIGuide_getJackpotWinners.md +83 -0
  139. package/docs/ui/jackpots/UIGuide_jackpotGet.md +138 -0
  140. package/docs/ui/jackpots/UIGuide_jackpotOptIn.md +85 -0
  141. package/docs/ui/jackpots/UIGuide_jackpotOptOut.md +65 -0
  142. package/docs/ui/leaderboard/UIGuide_getLeaderBoard.md +166 -0
  143. package/docs/ui/minigames/UIGuide_getMiniGames.md +153 -0
  144. package/docs/ui/minigames/UIGuide_getMiniGamesHistory.md +90 -0
  145. package/docs/ui/minigames/UIGuide_playMiniGame.md +150 -0
  146. package/docs/ui/minigames/UIGuide_playMiniGameBatch.md +128 -0
  147. package/docs/ui/raffles/UIGuide_claimRafflePrize.md +99 -0
  148. package/docs/ui/raffles/UIGuide_getRaffleDrawRun.md +117 -0
  149. package/docs/ui/raffles/UIGuide_getRaffleDrawRunsHistory.md +92 -0
  150. package/docs/ui/raffles/UIGuide_getRaffleWonPrizes.md +120 -0
  151. package/docs/ui/raffles/UIGuide_getRaffles.md +175 -0
  152. package/docs/ui/raffles/UIGuide_requestRaffleOptin.md +114 -0
  153. package/docs/ui/user/UIGuide_getActivityLog.md +130 -0
  154. package/docs/ui/user/UIGuide_getLevels.md +47 -42
  155. package/package.json +1 -1
  156. package/src/Base/ClassId.ts +2 -0
  157. package/src/Jackpots/JackpotDetails.ts +14 -15
  158. package/src/Jackpots/JackpotPot.ts +10 -6
  159. package/src/MiniGames/SAWGameType.ts +3 -0
  160. package/src/MiniGames/SAWTemplateUI.ts +10 -0
  161. package/src/Raffle/GetRaffleWonPrizesRequest.ts +12 -0
  162. package/src/Raffle/GetRaffleWonPrizesResponse.ts +56 -0
  163. package/src/Raffle/index.ts +3 -1
  164. package/src/SmarticoAPI.ts +14 -1
  165. package/src/SmarticoLib/index.ts +4 -0
  166. package/src/WSAPI/WSAPIAvatars.ts +267 -49
  167. package/src/WSAPI/WSAPIBonuses.ts +224 -10
  168. package/src/WSAPI/WSAPIGamePick.ts +538 -253
  169. package/src/WSAPI/WSAPIGeneral.ts +156 -14
  170. package/src/WSAPI/WSAPIInbox.ts +545 -56
  171. package/src/WSAPI/WSAPIJackpots.ts +297 -61
  172. package/src/WSAPI/WSAPILeaderBoard.ts +127 -13
  173. package/src/WSAPI/WSAPIMiniGames.ts +465 -49
  174. package/src/WSAPI/WSAPIRaffles.ts +592 -64
  175. package/src/WSAPI/WSAPITournaments.ts +3 -3
  176. package/src/WSAPI/WSAPITypes.ts +243 -132
  177. package/src/WSAPI/WSAPIUser.ts +193 -43
  178. package/tsconfig.json +9 -1
@@ -6,23 +6,81 @@ export declare class WSAPIJackpots extends WSAPIClans {
6
6
  /** @hidden */
7
7
  protected jackpotGetSignature: string;
8
8
  protected jackpotClearCache(): Promise<void>;
9
- /** Returns list of Jackpots that are active in the system and matching to the filter definition.
10
- * If filter is not provided, all active jackpots will be returned.
11
- * Filter can be used to get jackpots related to specific game or specific jackpot template.
12
- * You can call this method every second in order to get up to date information about current value of the jackpot(s) and present them to the end-users
9
+ /**
10
+ * Returns the user-eligible jackpots active for the label, fused with their live
11
+ * pot values. Each entry carries the static template (name, description, opt-in
12
+ * state, eligible games, currency) plus a freshly-fetched `pot` snapshot.
13
13
  *
14
- * **Example**:
15
- * ```
16
- * _smartico.api.jackpotGet({ related_game_id: 'wooko-slot' }).then((result) => {
17
- * console.log(result);
18
- * });
19
- * ```
14
+ * Designed to be polled at high frequency (every 1 second is fine) — the SDK
15
+ * splits the response into a 30-second template cache and a 1-second pot-value
16
+ * cache so consumers can render a live-counting pot amount without hammering
17
+ * the server for the static template data.
20
18
  *
21
- * **Example in the Visitor mode**:
22
- * ```
23
- * _smartico.vapi('EN').jackpotGet({ related_game_id: 'wooko-slot' }).then((result) => {
24
- * console.log(result);
25
- * });
19
+ * @remarks
20
+ * **Preconditions**
21
+ * - No prerequisite calls.
22
+ * - Visitor mode supported via `_smartico.vapi(lang).jackpotGet(...)`.
23
+ *
24
+ * **Server-side eligibility filtering**
25
+ * Jackpots are filtered server-side by the user's segments before being
26
+ * returned. Templates the user is ineligible for never appear in this
27
+ * response — there is no "locked" state to render. An empty result for a
28
+ * known-good user typically means none of the configured templates match
29
+ * the user's segments / level / brand.
30
+ *
31
+ * **Filter behavior**
32
+ * Passing `related_game_id` returns only jackpots linked to that game (from
33
+ * the operator's games catalog). Passing `jp_template_id` returns just that
34
+ * single template. With no filter, all active templates the user is
35
+ * eligible for are returned. Changing the filter between calls flushes both
36
+ * the template cache and the pot cache.
37
+ *
38
+ * **Two-tier cache**
39
+ * - Template definitions: 30 s cache. Re-fetched on filter change or when
40
+ * opt-in / opt-out / a jackpot-win push lands.
41
+ * - Pot values: 1 s cache. Re-fetched on every call past the 1-second
42
+ * window so a 1 Hz poll renders a smoothly counting pot.
43
+ *
44
+ * **`jp_public_meta.custom_data`**
45
+ * Server returns this as a JSON-encoded string; the SDK parses it inline so
46
+ * consumers always receive either a parsed object or the raw string.
47
+ *
48
+ * **Personal vs MultiUser jackpots** (see {@link JackpotType})
49
+ * - `MultiUser` (1) — shared pot; `registration_count` reflects real opted-in
50
+ * user count; temperature transitions fire push events.
51
+ * - `Personal` (2) — independent per-user pot; `registration_count` is
52
+ * always 1; temperature push events are suppressed.
53
+ *
54
+ * **Refresh**
55
+ * - `jp_status_id`, segment changes, and operator template edits surface
56
+ * after the 30 s template cache TTL.
57
+ * - Opt-in / opt-out / jackpot-win push events all clear the template and
58
+ * pot caches — the next call re-fetches.
59
+ *
60
+ * **Visitor mode**: supported.
61
+ *
62
+ * **UI guidance**: see [UI Guide — `jackpotGet`](../../docs/ui/jackpots/UIGuide_jackpotGet.md).
63
+ *
64
+ * @param filter Optional filter narrowing the result set.
65
+ * @param filter.related_game_id Limit to jackpots linked to this game ID
66
+ * (from the operator's games catalog).
67
+ * @param filter.jp_template_id Limit to a single template.
68
+ * @returns Array of {@link JackpotDetails} — empty if the user is eligible
69
+ * for no active jackpots.
70
+ *
71
+ * @example
72
+ * ```ts
73
+ * // Poll every second for live pot counter
74
+ * setInterval(async () => {
75
+ * const jackpots = await window._smartico.api.jackpotGet();
76
+ * for (const jp of jackpots) {
77
+ * console.log('[smartico] update pot widget for', jp.jp_public_meta.name, '— amount:', jp.pot.current_pot_amount_user_currency, jp.user_currency, '— temperature:', jp.pot.current_pot_temperature);
78
+ * }
79
+ * }, 1000);
80
+ *
81
+ * // Filtered fetch for a specific game tile
82
+ * const linked = await window._smartico.api.jackpotGet({ related_game_id: 'gold-slot2' });
83
+ * console.log('[smartico] linked jackpots for game:', linked.length);
26
84
  * ```
27
85
  */
28
86
  jackpotGet(filter?: {
@@ -30,80 +88,257 @@ export declare class WSAPIJackpots extends WSAPIClans {
30
88
  jp_template_id?: number;
31
89
  }): Promise<JackpotDetails[]>;
32
90
  /**
33
- * Opt-in currently logged in user to the jackpot with the specified jp_template_id.
34
- * You may call jackpotGet method after doing optin to see that user is opted in to the jackpot.
91
+ * Opts the authenticated user into a jackpot. From this point on, the user
92
+ * contributes to the pot (per the template's `contribution_type` and
93
+ * `contribution_value`) and is eligible to win when the pot explodes.
35
94
  *
36
- * **Example**:
37
- * ```
38
- * _smartico.api.jackpotOptIn({ jp_template_id: 123 }).then((result) => {
39
- * console.log('Opted in to the jackpot');
40
- * });
41
- * ```
95
+ * On success the SDK clears the jackpot caches — the next
96
+ * {@link jackpotGet} call returns the updated `is_opted_in: true` and an
97
+ * incremented `registration_count`.
98
+ *
99
+ * @remarks
100
+ * **Preconditions**
101
+ * - User must be authenticated. Visitor mode not supported.
102
+ * - `jp_template_id` is mandatory — the SDK throws synchronously if missing.
103
+ * - The jackpot must currently be active and the user must be in its
104
+ * eligibility segment. Ineligible jackpots are filtered out of
105
+ * {@link jackpotGet} entirely, so a card the user sees is opt-in-able.
106
+ *
107
+ * **Error handling**
108
+ * The server returns a non-zero `errCode` with a human-readable `errMsg`
109
+ * for any failure. Common causes:
110
+ * - User is in a control group.
111
+ * - Jackpot template is not active (status changed since the user opened
112
+ * the card).
113
+ * - User is already opted in (the SDK has no client-side guard against a
114
+ * double-tap; the server enforces).
115
+ * - DB race / generic server error.
116
+ *
117
+ * The SDK does NOT enumerate distinct numeric codes for each cause — branch
118
+ * on `errCode === 0` for success and surface `errMsg` as-is for failures.
119
+ *
120
+ * **Idempotency / re-opt-in semantics**
121
+ * - **Already opted in** → returns non-zero `errCode` ("User already opted in").
122
+ * - **Previously opted in then opted out** → succeeds silently; the server
123
+ * re-activates the registration. This is not an error path — a user can
124
+ * freely cycle opt-in / opt-out.
125
+ *
126
+ * **Refresh after success**
127
+ * - The SDK clears the template, pot, and winners caches.
128
+ * - The next {@link jackpotGet} call returns `is_opted_in: true` for this
129
+ * template.
130
+ *
131
+ * **Side effects**
132
+ * Fires a `JACKPOT_OPT_IN` engagement event (visible to operator-side
133
+ * automation rules). Does NOT immediately move points / gems — contributions
134
+ * happen per-bet via the user's gameplay, not on opt-in.
135
+ *
136
+ * **Visitor mode**: not supported.
42
137
  *
43
- * **Visitor mode: not supported**
138
+ * **UI guidance**: see [UI Guide — `jackpotOptIn`](../../docs/ui/jackpots/UIGuide_jackpotOptIn.md).
44
139
  *
140
+ * @param filter.jp_template_id ID of the jackpot template to join.
141
+ * @returns {@link JackpotsOptinResponse} — `errCode === 0` on success.
142
+ *
143
+ * @example
144
+ * ```ts
145
+ * const r = await window._smartico.api.jackpotOptIn({ jp_template_id: 42 });
146
+ *
147
+ * if (r.errCode === 0) {
148
+ * console.log('[smartico] opted in — refresh jackpot card to show opt-out CTA');
149
+ * } else {
150
+ * console.error('[smartico] opt-in failed — show this message in an error toast:', r.errMsg);
151
+ * }
152
+ * ```
45
153
  */
46
154
  jackpotOptIn(filter: {
47
155
  jp_template_id: number;
48
156
  }): Promise<JackpotsOptinResponse>;
49
157
  /**
50
- * Opt-out currently logged in user from the jackpot with the specified jp_template_id.
51
- * You may call jackpotGet method after doing optout to see that user is not opted in to the jackpot.
158
+ * Opts the authenticated user out of a jackpot. From this point on the user
159
+ * no longer contributes to the pot and is not eligible to win.
52
160
  *
53
- * **Example**:
54
- * ```
55
- * _smartico.api.jackpotOptOut({ jp_template_id: 123 }).then((result) => {
56
- * console.log('Opted out from the jackpot');
57
- * });
58
- * ```
161
+ * The user can re-join later via {@link jackpotOptIn} — opt-out is not
162
+ * permanent.
163
+ *
164
+ * @remarks
165
+ * **Preconditions**
166
+ * - User must be authenticated. Visitor mode not supported.
167
+ * - `jp_template_id` is mandatory — the SDK throws synchronously if missing.
168
+ *
169
+ * **Error handling**
170
+ * The server returns a non-zero `errCode` with a human-readable `errMsg` for
171
+ * any failure. Common causes:
172
+ * - User has never opted in OR is already opted out — server returns
173
+ * non-zero `errCode` for the "already opted out" case. Calling opt-out
174
+ * on a jackpot the user has never registered for typically returns
175
+ * success (the server finds no registration row to update).
176
+ * - DB race / generic server error.
59
177
  *
60
- * **Visitor mode: not supported**
178
+ * Unlike {@link jackpotOptIn}, opt-out does NOT check the template's status
179
+ * — the user can opt out of a jackpot that has been deactivated by the
180
+ * operator.
61
181
  *
182
+ * **Idempotency**
183
+ * - First opt-out → success.
184
+ * - Second opt-out → non-zero `errCode` ("Already opted out").
185
+ * - Opt-out of a never-joined jackpot → typically succeeds silently
186
+ * (no registration row to act on).
187
+ *
188
+ * **Refresh after success**
189
+ * - The SDK clears the template, pot, and winners caches.
190
+ * - The next {@link jackpotGet} call returns `is_opted_in: false` for this
191
+ * template and a decremented `registration_count`.
192
+ *
193
+ * **Side effects**
194
+ * Fires a `JACKPOT_OPT_OUT` engagement event for operator-side automation
195
+ * rules. The user's existing contributions to the current pot remain in
196
+ * place — opt-out stops future contributions but does not refund past ones.
197
+ *
198
+ * **Visitor mode**: not supported.
199
+ *
200
+ * **UI guidance**: see [UI Guide — `jackpotOptOut`](../../docs/ui/jackpots/UIGuide_jackpotOptOut.md).
201
+ *
202
+ * @param filter.jp_template_id ID of the jackpot template to leave.
203
+ * @returns {@link JackpotsOptoutResponse} — `errCode === 0` on success.
204
+ *
205
+ * @example
206
+ * ```ts
207
+ * const r = await window._smartico.api.jackpotOptOut({ jp_template_id: 42 });
208
+ *
209
+ * if (r.errCode === 0) {
210
+ * console.log('[smartico] opted out — refresh jackpot card to show join CTA');
211
+ * } else {
212
+ * console.error('[smartico] opt-out failed — show this message in an error toast:', r.errMsg);
213
+ * }
214
+ * ```
62
215
  */
63
216
  jackpotOptOut(filter: {
64
217
  jp_template_id: number;
65
218
  }): Promise<JackpotsOptoutResponse>;
66
219
  /**
67
- * Returns jackpot winners for the given `jp_template_id` (paginated on the server).
68
- * Default page size on the wire is 20; use `limit`, `offset`, and repeated calls to load more.
69
- * The full protocol response also includes `has_more`; this method returns only the `winners` array.
220
+ * Returns past winners of a specific jackpot template, paginated. Use to
221
+ * power a "Recent winners" panel inside the jackpot detail modal.
70
222
  *
71
- * **Example**:
72
- * ```
73
- * _smartico.api.getJackpotWinners({
74
- * jp_template_id: 123,
75
- * }).then((result) => {
76
- * console.log(result);
77
- * });
78
- * ```
223
+ * **Important**: respect the `expose_winners_over_api` flag on the jackpot's
224
+ * {@link JackpotDetails} before calling this method. The server-side handler
225
+ * does NOT enforce that flag — it is a UI-only gate. Custom UIs that ignore
226
+ * the flag will display winners the operator intended to keep private.
227
+ *
228
+ * @remarks
229
+ * **Preconditions**
230
+ * - User must be authenticated. Visitor mode not supported.
231
+ * - `jp_template_id` is mandatory — the SDK throws synchronously if missing.
232
+ * - The consumer SHOULD check
233
+ * {@link JackpotDetails.expose_winners_over_api} before calling, since
234
+ * the server does not enforce it.
235
+ *
236
+ * **Pagination**
237
+ * Server default page size is 20. Pass `limit` and `offset` to paginate
238
+ * (e.g. infinite-scroll). The wire response carries a `has_more` flag, but
239
+ * this SDK method returns only the `winners` array — detect end-of-list by
240
+ * a returned array shorter than `limit`.
241
+ *
242
+ * **Currency caveat**
243
+ * Winner amounts in the response (`winner.winning_amount_jp_currency`) are
244
+ * in the jackpot's NATIVE currency, NOT the user's wallet currency. If a
245
+ * user-currency display is needed, the consumer must convert client-side.
246
+ *
247
+ * **Refresh**
248
+ * - The SDK caches per `jp_template_id` for 30 seconds.
249
+ * - Caches clear on jackpot-win push events and on opt-in / opt-out.
250
+ *
251
+ * **Error handling**
252
+ * Non-zero `errCode` on control-group users or generic server errors. The
253
+ * SDK does NOT enumerate distinct codes — branch on `errCode === 0` and
254
+ * surface `errMsg` on failure.
255
+ *
256
+ * **Visitor mode**: not supported.
79
257
  *
80
- * **Visitor mode: not supported**
258
+ * **UI guidance**: see [UI Guide — `getJackpotWinners`](../../docs/ui/jackpots/UIGuide_getJackpotWinners.md).
81
259
  *
82
- * @param params - Jackpot winners parameters
83
- * @param params.jp_template_id - Jackpot template id (required; throws if missing)
84
- * @param params.limit - Page size (server default 20 when omitted)
85
- * @param params.offset - Offset into the winner list
260
+ * @returns Array of {@link JackpotWinnerHistory} entries newest-first.
261
+ *
262
+ * @example
263
+ * ```ts
264
+ * const [jp] = await window._smartico.api.jackpotGet({ jp_template_id: 42 });
265
+ *
266
+ * if (!jp || !jp.expose_winners_over_api) {
267
+ * console.log('[smartico] winners hidden by operator config — hide the winners tab');
268
+ * return;
269
+ * }
270
+ *
271
+ * const winners = await window._smartico.api.getJackpotWinners({
272
+ * jp_template_id: 42,
273
+ * limit: 20,
274
+ * offset: 0,
275
+ * });
276
+ * console.log('[smartico] render', winners.length, 'recent winner rows (amounts in', jp.jp_currency + ')');
277
+ * ```
86
278
  */
87
279
  getJackpotWinners({ limit, offset, jp_template_id, }: {
280
+ /** Page size (default 20). */
88
281
  limit?: number;
282
+ /** Pagination offset (default 0). */
89
283
  offset?: number;
284
+ /** Jackpot template ID (required). */
90
285
  jp_template_id?: number;
91
286
  }): Promise<JackpotWinnerHistory[]>;
92
287
  /**
93
- * Returns the eligible games for the jackpot with the specified jp_template_id.
288
+ * Returns the casino games eligible to contribute to a specific jackpot —
289
+ * the catalog the user must play to grow the pot. Use to power an
290
+ * "Eligible games" carousel inside the jackpot detail modal.
94
291
  *
95
- * **Example**:
96
- * ```
97
- * _smartico.api.getJackpotEligibleGames({ jp_template_id: 123 }).then((result) => {
98
- * console.log(result);
99
- * });
100
- * ```
292
+ * **Shortcut**: when the jackpot's
293
+ * {@link JackpotDetails.ach_related_game_allow_all} flag is `true`, every
294
+ * game in the operator catalog contributes — there's no point calling this
295
+ * method (the result would be the full catalog). The default Smartico UI
296
+ * hides the Eligible Games tab entirely in that case.
297
+ *
298
+ * @remarks
299
+ * **Preconditions**
300
+ * - User must be authenticated. Visitor mode not supported.
301
+ * - `jp_template_id` is mandatory.
101
302
  *
102
- * **Visitor mode: not supported**
303
+ * **`onUpdate` caveat**
304
+ * The `onUpdate` callback is accepted to match the SDK's subscription
305
+ * contract but is NOT auto-invoked by any current server push. It will only
306
+ * fire if a consumer (or a future SDK version) explicitly pushes an update.
307
+ * Treat it as a no-op for now.
103
308
  *
309
+ * **Refresh**
310
+ * - The SDK caches per `jp_template_id` for 30 seconds.
311
+ * - Cache does NOT clear on opt-in / opt-out / jackpot-win — eligible-game
312
+ * lists rarely change during a session. Wait for the 30 s TTL.
313
+ *
314
+ * **Error handling**
315
+ * Non-zero `errCode` on control-group users or generic server errors.
316
+ * Branch on `errCode === 0` and surface `errMsg` on failure.
317
+ *
318
+ * **Visitor mode**: not supported.
319
+ *
320
+ * **UI guidance**: see [UI Guide — `getJackpotEligibleGames`](../../docs/ui/jackpots/UIGuide_getJackpotEligibleGames.md).
321
+ *
322
+ * @returns {@link TGetJackpotEligibleGamesResponse} —
323
+ * `{ eligible_games: JackpotEligibleGame[] }`.
324
+ *
325
+ * @example
326
+ * ```ts
327
+ * const [jp] = await window._smartico.api.jackpotGet({ jp_template_id: 42 });
328
+ *
329
+ * if (jp?.ach_related_game_allow_all) {
330
+ * console.log('[smartico] all games eligible — hide the eligible-games tab');
331
+ * return;
332
+ * }
333
+ *
334
+ * const r = await window._smartico.api.getJackpotEligibleGames({ jp_template_id: 42 });
335
+ * console.log('[smartico] render', r.eligible_games.length, 'eligible game tiles');
336
+ * ```
104
337
  */
105
338
  getJackpotEligibleGames({ jp_template_id, onUpdate }: {
339
+ /** Jackpot template ID (required). */
106
340
  jp_template_id: number;
341
+ /** Optional callback; not auto-invoked today. */
107
342
  onUpdate?: () => void;
108
343
  }): Promise<TGetJackpotEligibleGamesResponse>;
109
344
  }
@@ -4,21 +4,135 @@ import { WSAPIGamePick } from './WSAPIGamePick';
4
4
  /** @group LeaderBoard */
5
5
  export declare class WSAPILeaderBoard extends WSAPIGamePick {
6
6
  /**
7
- * Returns the leaderboard for the current type (default is Daily). If getPreviousPeriod is passed as true, a leaderboard for the previous period for the current type will be returned.
8
- * For example, if the type is Weekly and getPreviousPeriod is true, a leaderboard for the previous week will be returned.
7
+ * Returns the operator-configured standalone leaderboard for the
8
+ * given period type — top-20 ranked entries, the current user's
9
+ * own entry (when authenticated), and the configured prize table.
10
+ * Use this to power a leaderboard page with daily / weekly /
11
+ * monthly tabs.
9
12
  *
10
- * **Example**:
11
- * ```
12
- * _smartico.api.getLeaderBoard(1).then((result) => {
13
- * console.log(result);
14
- * });
15
- * ```
13
+ * The leaderboard for each period type is configured separately by
14
+ * the operator. A label may have any combination of DAILY, WEEKLY,
15
+ * and MONTHLY boards configured (or none).
16
16
  *
17
- * **Example in the Visitor mode**:
18
- * ```
19
- * _smartico.vapi('EN').getLeaderBoard(1).then((result) => {
20
- * console.log(result);
21
- * });
17
+ * @remarks
18
+ * **Return value note** — the runtime may return `undefined` if no
19
+ * board is configured for the requested `periodType`, despite the
20
+ * static return type being `Promise<LeaderBoardDetailsT>`. Defend
21
+ * against that case in consumer code.
22
+ *
23
+ * **Preconditions**
24
+ * Pass a `periodType` from {@link LeaderBoardPeriodType}
25
+ * (`DAILY = 1`, `WEEKLY = 2`, `MONTHLY = 3`). Pass
26
+ * `getPreviousPeriod: true` to fetch the most-recently-ended
27
+ * period's snapshot (yesterday's results, last week's results,
28
+ * last month's results) instead of the current live period. The
29
+ * SDK only exposes one period back — older snapshots are not
30
+ * reachable through this method.
31
+ *
32
+ * **Top-20 cap**
33
+ * The server hard-caps `users[]` at 20 entries, ordered by
34
+ * `position` ASC. Position values are server-computed (DENSE_RANK
35
+ * over all participants); the truncation at 20 is for transport
36
+ * size only — `position` may exceed 20 elsewhere.
37
+ *
38
+ * **The `me` field**
39
+ * Always populated for authenticated users (even when they have
40
+ * zero points in the period). `me.position === -1` is the signal
41
+ * that the user is active but ranked outside the top 20 (or has no
42
+ * activity yet). `me` is `undefined` for visitor-mode sessions.
43
+ *
44
+ * **Rewards are points only**
45
+ * `rewards[].points` are gamification points credited to the user's
46
+ * balance when the period finalizes. The leaderboard never awards
47
+ * gems, diamonds, store items, or bonuses. The first element of
48
+ * the array is the prize for place 1, the second for place 2, and
49
+ * so on. The array length is the number of paid places.
50
+ *
51
+ * **Cache TTL — single shared key (known limitation)**
52
+ * The SDK caches the response for 30 seconds under a SINGLE shared
53
+ * key — calling `getLeaderBoard(DAILY)` followed by
54
+ * `getLeaderBoard(WEEKLY)` within the same 30 s window returns the
55
+ * cached DAILY result for the WEEKLY call. Same applies to
56
+ * switching `getPreviousPeriod`. To force a fresh fetch when
57
+ * switching periods or current/previous, call
58
+ * `_smartico.api.clearCaches()` before the second call, or simply
59
+ * wait out the TTL.
60
+ *
61
+ * **Period boundaries**
62
+ * The server finalizes each period on a server-configurable
63
+ * schedule: DAILY at midnight + operator-defined offset; WEEKLY
64
+ * at the start of Monday; MONTHLY on the 1st of each month. At
65
+ * finalization, the server distributes the configured `rewards[]`
66
+ * points to the top placeholders and resets the live board. After
67
+ * finalization, `getLeaderBoard(periodType, false)` returns the
68
+ * NEW (empty) period's board; call with
69
+ * `getPreviousPeriod: true` to see the just-ended standings.
70
+ *
71
+ * **Refresh model**
72
+ * - One-shot fetch (no subscription).
73
+ * - No push event refreshes the cache; finalization at the period
74
+ * boundary is NOT pushed to the client.
75
+ * - Poll manually if the consumer needs near-live state during an
76
+ * in-progress period.
77
+ *
78
+ * **Idempotency / Side effects**: safe. Read-only.
79
+ *
80
+ * **UI guidance**: see [UI Guide — `getLeaderBoard`](../../docs/ui/leaderboard/UIGuide_getLeaderBoard.md).
81
+ *
82
+ * **Visitor mode**: supported. The same shape is returned, scoped
83
+ * to the brand's public leaderboard. `me` is `undefined` for
84
+ * visitors.
85
+ *
86
+ * @param periodType The board's period type
87
+ * ({@link LeaderBoardPeriodType}).
88
+ * Selects which pre-configured board to
89
+ * fetch; the board itself is bound to one
90
+ * period by the operator.
91
+ * @param getPreviousPeriod When `true`, returns the most recent
92
+ * finalized snapshot for that period type
93
+ * (e.g. last week's results). Defaults to
94
+ * `false` (current in-progress period).
95
+ * @returns Promise resolving to `LeaderBoardDetailsT`.
96
+ * **At runtime, may resolve to `undefined`**
97
+ * when no board is configured for the
98
+ * requested period type — guard against it.
99
+ *
100
+ * @example
101
+ * ```ts
102
+ * import { LeaderBoardPeriodType } from '@smartico/public-api';
103
+ *
104
+ * const board = await window._smartico.api.getLeaderBoard(LeaderBoardPeriodType.WEEKLY);
105
+ *
106
+ * if (!board) {
107
+ * console.log('[smartico] no weekly board configured for this label — hide the leaderboard surface');
108
+ * return;
109
+ * }
110
+ *
111
+ * console.log('[smartico] render leaderboard tab —', board.name, '—', board.users.length, 'ranked entries (top 20 max)');
112
+ *
113
+ * // Render prize table.
114
+ * for (const reward of board.rewards) {
115
+ * console.log('[smartico] prize row — place', reward.place, '→', reward.points, 'points');
116
+ * }
117
+ *
118
+ * // "Me" panel — sticky row showing the current user's rank.
119
+ * if (board.me) {
120
+ * if (board.me.position === -1) {
121
+ * console.log('[smartico] user is unranked — show "You are unranked, earn points to enter the leaderboard"');
122
+ * } else if (board.me.position > 20) {
123
+ * console.log('[smartico] user is ranked', board.me.position, 'but outside the visible top-20 — show sticky "me" row with', board.me.points, 'points');
124
+ * } else {
125
+ * console.log('[smartico] user is in the top 20 at position', board.me.position, '— highlight their row in the main list');
126
+ * }
127
+ * }
128
+ *
129
+ * // Switch to previous period view — but bust the cache first to avoid the shared-key collision.
130
+ * await window._smartico.api.clearCaches();
131
+ * const prev = await window._smartico.api.getLeaderBoard(LeaderBoardPeriodType.WEEKLY, true);
132
+ * console.log('[smartico] previous-week standings — render with greyed-out "ended" treatment:', prev?.users.length, 'finalists');
133
+ *
134
+ * // Visitor-mode equivalent — me is always undefined.
135
+ * // const visitorBoard = await window._smartico.vapi('EN').getLeaderBoard(LeaderBoardPeriodType.DAILY);
22
136
  * ```
23
137
  */
24
138
  getLeaderBoard(periodType: LeaderBoardPeriodType, getPreviousPeriod?: boolean): Promise<LeaderBoardDetailsT>;