@smartico/public-api 0.0.379 → 0.0.380

package/dist/index.modern.mjs

@@ -949,6 +949,10 @@ var InboxReadStatus;
 
 var BuyStoreItemErrorCode;
 (function (BuyStoreItemErrorCode) {
+  /** Generic server error / control-group rejection */
+  BuyStoreItemErrorCode[BuyStoreItemErrorCode["SHOP_FAILED_GENERIC"] = 1] = "SHOP_FAILED_GENERIC";
+  /** Label mismatch detected before purchase transaction */
+  BuyStoreItemErrorCode[BuyStoreItemErrorCode["SHOP_WRONG_LABEL_PRECHECK"] = 106] = "SHOP_WRONG_LABEL_PRECHECK";
   /** User don't have enough points on balance */
   BuyStoreItemErrorCode[BuyStoreItemErrorCode["SHOP_NO_BALANCE"] = 11000] = "SHOP_NO_BALANCE";
   /** Wrong shop item id */
@@ -963,6 +967,8 @@ var BuyStoreItemErrorCode;
   BuyStoreItemErrorCode[BuyStoreItemErrorCode["SHOP_FAILED_TO_BUY_MATCHING_BONUS"] = 11005] = "SHOP_FAILED_TO_BUY_MATCHING_BONUS";
   /** Failed to buy item because of limit of max items is reached */
   BuyStoreItemErrorCode[BuyStoreItemErrorCode["SHOP_FAILED_MAX_BOUGHT_ITEMS_REACHED"] = 11006] = "SHOP_FAILED_MAX_BOUGHT_ITEMS_REACHED";
+  /** Bonus was issued but a follow-up redemption step failed */
+  BuyStoreItemErrorCode[BuyStoreItemErrorCode["SHOP_FAILED_BONUS_REDEMPTION"] = 11007] = "SHOP_FAILED_BONUS_REDEMPTION";
   /** Failed to buy item because no more items are available */
   BuyStoreItemErrorCode[BuyStoreItemErrorCode["SHOP_FAILED_POOL_EMPTY"] = 11009] = "SHOP_FAILED_POOL_EMPTY";
   /** User doesn't have enough gems on balance */
@@ -971,6 +977,8 @@ var BuyStoreItemErrorCode;
   BuyStoreItemErrorCode[BuyStoreItemErrorCode["SHOP_NO_BALANCE_DIAMONDS"] = 11012] = "SHOP_NO_BALANCE_DIAMONDS";
   /** Failed to buy item because of purchase limitation */
   BuyStoreItemErrorCode[BuyStoreItemErrorCode["SHOP_FAILED_PURCHASE_LIMITATION"] = 11014] = "SHOP_FAILED_PURCHASE_LIMITATION";
+  /** Uncaught server exception */
+  BuyStoreItemErrorCode[BuyStoreItemErrorCode["SHOP_UNEXPECTED_EXCEPTION"] = 9999] = "SHOP_UNEXPECTED_EXCEPTION";
 })(BuyStoreItemErrorCode || (BuyStoreItemErrorCode = {}));
 
 const StoreCategoryTransform = items => {
@@ -1014,7 +1022,7 @@ var StoreItemTypeName;
 const StoreItemTypeNamed = type => {
   return {
     [StoreItemType.Bonus]: StoreItemTypeName.Bonus,
-    [StoreItemType.Tangible]: StoreItemTypeName.Bonus,
+    [StoreItemType.Tangible]: StoreItemTypeName.Tangible,
     [StoreItemType.MiniGameSpin]: StoreItemTypeName.MiniGameSpin,
     [StoreItemType.ChangeLevel]: StoreItemTypeName.ChangeLevel,
     [StoreItemType.PrizeDrop]: StoreItemTypeName.PrizeDrop,
@@ -1054,6 +1062,7 @@ const StoreItemTransform = items => {
       pool: r.shopPool,
       custom_data: IntUtils.JsonOrText(r.itemPublicMeta.custom_data),
       active_till_date: r.activeTillDate,
+      show_timer: r.itemPublicMeta.show_timer,
       discounted_price: r.itemPublicMeta.discount_prize,
       discount_price_ribbon: r.itemPublicMeta.discount_prize_ribbon,
       custom_ribbon_image: r.itemPublicMeta.custom_ribbon_image,
@@ -1120,6 +1129,7 @@ const StoreItemPurchasedTransform = items => {
       purchased_this_week: purchasedThisWeek,
       purchased_this_month: purchasedThisMonth,
       custom_data: r.itemPublicMeta.custom_data,
+      show_timer: r.itemPublicMeta.show_timer,
       related_games: (((_r$relatedGames = r.relatedGames) == null ? void 0 : _r$relatedGames.filter(g => g.game_public_meta.enabled)) || []).map((g, i) => ({
         ext_game_id: g.ext_game_id,
         game_public_meta: {
@@ -1243,7 +1253,7 @@ var BadgesTimeLimitStates;
 
 var _MissionUtils;
 const USER_STATE_PARAMS_KEYS_GAMES = ['core_fav_game_top3', 'core_fav_game_type_top3', 'core_fav_game_provider_top3'];
-const USER_STATE_PARAMS_KEYS_BET_AMOUNT = ['core_recommended_deposit_amount', 'core_recommended_casino_bet_amount', 'casino_last_bet_amount', 'casino_last_bet_amount_real', 'casino_last_bet_amount_bonus', 'acc_last_deposit_amount'];
+const USER_STATE_PARAMS_KEYS_BET_AMOUNT = ['core_recommended_deposit_amount', 'core_recommended_casino_bet_amount'];
 const MINOR_WORDS = new Set(['of', 'at', 'in', 'on', 'to', 'up', 'as', 'by', 'for', 'from', 'into', 'onto', 'with', 'upon', 'via', 'and', 'but', 'or', 'nor', 'so', 'yet', 'vs', 'v', 'a', 'an', 'the']);
 function toGameTitleCase(raw) {
   if (!raw) return raw;
@@ -2003,6 +2013,8 @@ var TournamentRegistrationError;
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_USER_NOT_REGISTERED"] = 30006] = "TOURNAMENT_USER_NOT_REGISTERED";
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_CANT_CHANGE_REGISTRATION_STATUS"] = 30007] = "TOURNAMENT_CANT_CHANGE_REGISTRATION_STATUS";
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_MAX_REGISTRATIONS_REACHED"] = 30008] = "TOURNAMENT_MAX_REGISTRATIONS_REACHED";
+  TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_REGISTRATION_NOT_ENOUGH_GEMS"] = 30010] = "TOURNAMENT_REGISTRATION_NOT_ENOUGH_GEMS";
+  TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_REGISTRATION_NOT_ENOUGH_DIAMONDS"] = 30011] = "TOURNAMENT_REGISTRATION_NOT_ENOUGH_DIAMONDS";
 })(TournamentRegistrationError || (TournamentRegistrationError = {}));
 
 var TournamentType;
@@ -2085,6 +2097,92 @@ const GetLevelMapResponseTransform = levels => {
   }));
 };
 
+/** @hidden */
+const CACHE_DATA_SEC = 30;
+/** @hidden */
+const JACKPOT_TEMPLATE_CACHE_SEC = 30;
+/** @hidden */
+const JACKPOT_POT_CACHE_SEC = 1;
+/** @hidden */
+const JACKPOT_WINNERS_CACHE_SEC = 30;
+/** @hidden */
+const JACKPOT_ELIGIBLE_GAMES_CACHE_SEC = 30;
+/** @hidden */
+var onUpdateContextKey;
+(function (onUpdateContextKey) {
+  onUpdateContextKey["Saw"] = "saw";
+  onUpdateContextKey["Missions"] = "missions";
+  onUpdateContextKey["TournamentList"] = "tournamentList";
+  onUpdateContextKey["InboxMessages"] = "inboxMessages";
+  onUpdateContextKey["Badges"] = "badges";
+  onUpdateContextKey["Levels"] = "levels";
+  onUpdateContextKey["StoreItems"] = "storeItems";
+  onUpdateContextKey["StoreCategories"] = "storeCategories";
+  onUpdateContextKey["AchCategories"] = "achCategories";
+  onUpdateContextKey["LeaderBoards"] = "leaderBoards";
+  onUpdateContextKey["LevelExtraCounters"] = "levelExtraCounters";
+  onUpdateContextKey["Segments"] = "segments";
+  onUpdateContextKey["StoreHistory"] = "storeHistory";
+  onUpdateContextKey["Jackpots"] = "jackpots";
+  onUpdateContextKey["Pots"] = "Pots";
+  onUpdateContextKey["CustomSections"] = "customSections";
+  onUpdateContextKey["Bonuses"] = "bonuses";
+  onUpdateContextKey["Clans"] = "clans";
+  onUpdateContextKey["SAWHistory"] = "sawHistory";
+  onUpdateContextKey["JackpotWinners"] = "jackpotWinners";
+  onUpdateContextKey["Raffles"] = "raffles";
+  onUpdateContextKey["JackpotEligibleGames"] = "jackpotEligibleGames";
+  onUpdateContextKey["CurrentLevel"] = "currentLevel";
+  onUpdateContextKey["InboxUnreadCount"] = "inboxUnreadCount";
+  onUpdateContextKey["ActivityLog"] = "activityLog";
+  onUpdateContextKey["AvatarsList"] = "avatarsList";
+  onUpdateContextKey["AvatarsCustomized"] = "avatarsCustomized";
+  onUpdateContextKey["AvatarPrompts"] = "avatarPrompts";
+})(onUpdateContextKey || (onUpdateContextKey = {}));
+/**
+ * Abstract base of the SDK's public surface. Holds the shared state
+ * (`api`, `userExtId`, `onUpdateCallback` map) and the generic cache /
+ * subscription helper (`updateEntity`). Domain-specific methods live on
+ * subclasses; the terminator `WSAPI` class composes the whole chain.
+ *
+ * **Consumers should not instantiate this directly** — the SDK constructs
+ * the concrete `WSAPI` via `_smartico.api`.
+ *
+ * @hidden
+ */
+class WSAPIBase {
+  /** @private */
+  constructor(api, userExtId = null) {
+    this.api = void 0;
+    /** @hidden */
+    this.onUpdateCallback = new Map();
+    /** @hidden */
+    this.userExtId = null;
+    this.api = api;
+    this.userExtId = userExtId;
+    OCache.clearAll();
+  }
+  /** @private */
+  // AA: this method is used from the _smartico script to clear cache when the context is changed,
+  // e.g. when user is changed or language is changed
+  clearCaches() {
+    OCache.clearAll();
+  }
+  /**
+   * Generic cache-update + subscription-notify helper. Used by domain
+   * classes' `update*` methods to refresh a context and fire any
+   * registered `onUpdate` callback.
+   * @hidden
+   */
+  async updateEntity(contextKey, payload) {
+    OCache.set(contextKey, payload, ECacheContext.WSAPI);
+    const onUpdate = this.onUpdateCallback.get(contextKey);
+    if (onUpdate) {
+      onUpdate(payload);
+    }
+  }
+}
+
 /** @hidden */
 const ticketsTransform = items => {
   return items.map(item => {
@@ -2285,119 +2383,120 @@ const raffleClaimPrizeResponseTransform = info => {
   };
 };
 
-/** @hidden */
-const CACHE_DATA_SEC = 30;
-const JACKPOT_TEMPLATE_CACHE_SEC = 30;
-const JACKPOT_POT_CACHE_SEC = 1;
-const JACKPOT_WINNERS_CACHE_SEC = 30;
-const JACKPOT_ELIGIBLE_GAMES_CACHE_SEC = 30;
-/** @hidden */
-var onUpdateContextKey;
-(function (onUpdateContextKey) {
-  onUpdateContextKey["Saw"] = "saw";
-  onUpdateContextKey["Missions"] = "missions";
-  onUpdateContextKey["TournamentList"] = "tournamentList";
-  onUpdateContextKey["InboxMessages"] = "inboxMessages";
-  onUpdateContextKey["Badges"] = "badges";
-  onUpdateContextKey["Levels"] = "levels";
-  onUpdateContextKey["StoreItems"] = "storeItems";
-  onUpdateContextKey["StoreCategories"] = "storeCategories";
-  onUpdateContextKey["AchCategories"] = "achCategories";
-  onUpdateContextKey["LeaderBoards"] = "leaderBoards";
-  onUpdateContextKey["LevelExtraCounters"] = "levelExtraCounters";
-  onUpdateContextKey["Segments"] = "segments";
-  onUpdateContextKey["StoreHistory"] = "storeHistory";
-  onUpdateContextKey["Jackpots"] = "jackpots";
-  onUpdateContextKey["Pots"] = "Pots";
-  onUpdateContextKey["CustomSections"] = "customSections";
-  onUpdateContextKey["Bonuses"] = "bonuses";
-  onUpdateContextKey["Clans"] = "clans";
-  onUpdateContextKey["SAWHistory"] = "sawHistory";
-  onUpdateContextKey["JackpotWinners"] = "jackpotWinners";
-  onUpdateContextKey["Raffles"] = "raffles";
-  onUpdateContextKey["JackpotEligibleGames"] = "jackpotEligibleGames";
-  onUpdateContextKey["CurrentLevel"] = "currentLevel";
-  onUpdateContextKey["InboxUnreadCount"] = "inboxUnreadCount";
-  onUpdateContextKey["ActivityLog"] = "activityLog";
-  onUpdateContextKey["AvatarsList"] = "avatarsList";
-  onUpdateContextKey["AvatarsCustomized"] = "avatarsCustomized";
-  onUpdateContextKey["AvatarPrompts"] = "avatarPrompts";
-})(onUpdateContextKey || (onUpdateContextKey = {}));
-/** @group General API */
-class WSAPI {
-  /** @private */
-  constructor(api, userExtId = null) {
-    this.api = void 0;
-    this.onUpdateCallback = new Map();
-    this.jackpotGetSignature = '';
-    this.userExtId = null;
-    this.api = api;
-    this.userExtId = userExtId;
-    OCache.clearAll();
-    if (this.api.tracker) {
-      const on = this.api.tracker.on;
-      on(ClassId.SAW_SPINS_COUNT_PUSH, data => this.updateOnSpin(data));
-      on(ClassId.SAW_SHOW_SPIN_PUSH, () => this.reloadMiniGameTemplate());
-      on(ClassId.SAW_AKNOWLEDGE_RESPONSE, () => {
-        this.reloadMiniGameTemplate();
-        OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
-      });
-      on(ClassId.SAW_DO_SPIN_RESPONSE, () => {
-        this.reloadMiniGameTemplate();
-        OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
-      });
-      on(ClassId.MISSION_OPTIN_RESPONSE, () => this.updateMissions());
-      on(ClassId.ACHIEVEMENT_CLAIM_PRIZE_RESPONSE, () => this.updateMissions());
-      on(ClassId.RELOAD_ACHIEVEMENTS_EVENT, () => this.updateMissions());
-      on(ClassId.TOURNAMENT_REGISTER_RESPONSE, () => this.updateTournaments());
-      on(ClassId.BUY_SHOP_ITEM_RESPONSE, () => {
-        this.updateStorePurchasedItems();
-        this.updateStoreItems();
-      });
-      on(ClassId.CLIENT_ENGAGEMENT_EVENT_NEW, () => this.updateInboxMessages());
-      on(ClassId.LOGOUT_RESPONSE, () => OCache.clearContext(ECacheContext.WSAPI));
-      on(ClassId.IDENTIFY_RESPONSE, () => OCache.clearContext(ECacheContext.WSAPI));
-      on(ClassId.JP_WIN_PUSH, data => this.jackpotClearCache());
-      on(ClassId.JP_OPTOUT_RESPONSE, data => this.jackpotClearCache());
-      on(ClassId.JP_OPTIN_RESPONSE, data => this.jackpotClearCache());
-      on(ClassId.CLAIM_BONUS_RESPONSE, () => this.updateBonuses());
-      on(ClassId.SAW_DO_SPIN_BATCH_RESPONSE, () => {
-        this.reloadMiniGameTemplate();
-        OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
-      });
-      on(ClassId.RAF_CLAIM_PRIZE_RESPONSE, () => this.updateRaffles());
-      on(ClassId.GET_INBOX_MESSAGES_RESPONSE, res => {
-        if (res.unread_count !== undefined && res.unread_count !== null) {
-          this.updateInboxUnreadCount(res.unread_count);
-        }
-      });
-      on(ClassId.CLIENT_PUBLIC_PROPERTIES_CHANGED_EVENT, data => {
-        var _data$props, _data$props2, _data$props3, _data$props4, _data$props5;
-        if ((data == null || (_data$props = data.props) == null ? void 0 : _data$props.core_inbox_unread_count) !== undefined && (data == null || (_data$props2 = data.props) == null ? void 0 : _data$props2.core_inbox_unread_count) !== null) {
-          this.updateInboxUnreadCount(data.props.core_inbox_unread_count);
-        }
-        if ((data == null || (_data$props3 = data.props) == null ? void 0 : _data$props3.ach_points_balance) !== undefined || (data == null || (_data$props4 = data.props) == null ? void 0 : _data$props4.ach_gems_balance) !== undefined || (data == null || (_data$props5 = data.props) == null ? void 0 : _data$props5.ach_diamonds_balance) !== undefined) {
-          this.notifyActivityLogUpdate();
-        }
-      });
-      on(ClassId.RAF_OPTIN_RESPONSE, () => this.updateRaffles());
-    }
-  }
-  /** @private */
-  // AA: this method is used from the _smartico script to clear cache when the context is changed,
-  // e.g. when user is changed or language is changed
-  clearCaches() {
-    OCache.clearAll();
-  }
-  /** Returns information about current user
-   * Pay attention that this method is synchronous and returns the user profile object immediately, not a promise.
-   * **Example**:
-   * ```
-   * var p = _smartico.api.getUserProfile();
-   * console.log(p);
+/** @group User */
+class WSAPIUser extends WSAPIBase {
+  /**
+   * Returns the current user's public profile — the source of truth for
+   * balances (points / gems / diamonds), the current level ID, the
+   * display username + avatar, language, public tags, and the inbox
+   * unread count. **This method is synchronous** (returns `TUserProfile`,
+   * not a Promise): the SDK keeps a local snapshot of the user's public
+   * properties that is initialised at identify time and kept live by a
+   * server-driven update channel — every call returns the latest cached
+   * values without a network round-trip.
+   *
+   * Subscribe to changes by registering a callback on `_smartico.on('props_change', ...)`
+   * — the callback fires with the full snapshot at identify and with
+   * partial-key updates on every subsequent server push (typically
+   * under 1 second after the underlying state change).
+   *
+   * @remarks
+   * **Preconditions**
+   * The tracker must be initialised — calling this before the identify
+   * round-trip completes throws (`"Tracker is not initialized, cannot
+   * getUserProfile"`). Safe ways to wait for readiness:
+   * - register `_smartico.on('identify', (errCode, props) => ...)` —
+   *   fires once after a successful identify with the full props
+   * - register `_smartico.on('props_change', () => ...)` — fires first
+   *   at identify with the full snapshot, then on every push update
+   *
+   * **What's kept live (push-updated)**
+   * Balance fields (`ach_points_balance`, `ach_gems_balance`,
+   * `ach_diamonds_balance`, `ach_points_ever`), `ach_level_current_id`,
+   * `core_public_tags`, `core_inbox_unread_count`, `core_user_language`,
+   * `avatar_url`, `public_username`, and the AI-driven recommended-amount
+   * fields all flow over the SDK's user-properties update channel as
+   * partial updates — the snapshot is patched in place when any of them
+   * change server-side. Re-call `getUserProfile()` (or watch
+   * `props_change`) to observe new values.
+   *
+   * **Reading state from the returned profile**
+   * Balances (`ach_points_balance`, `ach_gems_balance`,
+   * `ach_diamonds_balance`) are the canonical source for affordability
+   * checks across the SDK — compare against `entry_fee_amount` (clans),
+   * `registration_cost_points` / `_gems` / `_diamonds` (tournaments), and
+   * `price` / `discounted_price` + `purchase_type` (store items).
+   * `ach_points_ever` is monotonic — store purchases deduct from
+   * `ach_points_balance` but NEVER from `ach_points_ever`, so it remains
+   * useful for level-progress math (`required_points` on the next
+   * {@link getLevels} entry minus `ach_points_ever`). `ach_level_current_id`
+   * is the FK into the level ladder — resolve metadata via
+   * {@link getCurrentLevel} (richer, includes progress %) or
+   * {@link getLevels} (full ladder lookup table).
+   *
+   * **Inbox unread count** — `core_inbox_unread_count` on this profile
+   * is push-updated in real time (under 1 second). For an inbox badge,
+   * prefer this field over {@link getInboxUnreadCount} (which is cached
+   * for 30 s) — same value, fresher signal.
+   *
+   * **Language**: `core_user_language` reflects the server's stored
+   * language. If the consumer just called `_smartico.changeLanguage(...)`,
+   * the field may briefly lag the local intent until the server push
+   * arrives. Use `_smartico.getPublicProps()` for the
+   * client-fallback-applied version if instant accuracy matters.
+   *
+   * **Idempotency / Side effects**: trivially safe — no network call,
+   * no state mutation.
+   *
+   * **UI guidance**: see [UI Guide — `getUserProfile`](../../docs/ui/user/UIGuide_getUserProfile.md).
+   *
+   * **Visitor mode**: not supported — throws. Visitor sessions do not
+   * have a public-profile snapshot.
+   *
+   * @returns The current cached `TUserProfile` snapshot. A shallow copy —
+   *          mutating it does not affect the SDK's internal state.
+   * @throws  `Error("Tracker is not initialized, cannot getUserProfile")`
+   *          if called before identify completes or from a visitor session.
+   *
+   * @example
+   * ```ts
+   * // Wait for identify before calling.
+   * window._smartico.on('identify', (errCode) => {
+   *   if (errCode !== 0) return;
+   *   const profile = window._smartico.api.getUserProfile();
+   *   console.log('[smartico] initial profile loaded — render the user widget:', profile);
+   * });
+   *
+   * // Stay in sync with live updates.
+   * window._smartico.on('props_change', (changed) => {
+   *   // `changed` is the partial keys for this push (full snapshot at identify).
+   *   const profile = window._smartico.api.getUserProfile();
+   *   console.log('[smartico] profile updated — re-render any widgets bound to:', Object.keys(changed),
+   *     '— balances now:', profile.ach_points_balance, profile.ach_gems_balance, profile.ach_diamonds_balance);
+   *
+   *   // React to specific fields.
+   *   if ('ach_level_current_id' in changed) {
+   *     console.log('[smartico] level changed — call getCurrentLevel() for richer detail, animate the level badge');
+   *   }
+   *   if ('core_inbox_unread_count' in changed) {
+   *     console.log('[smartico] inbox unread count changed — update the badge to:', profile.core_inbox_unread_count);
+   *   }
+   * });
+   *
+   * // Affordability gating example — used inside a clan / tournament / store CTA handler.
+   * const profile = window._smartico.api.getUserProfile();
+   * const item = await window._smartico.api.getStoreItems().then(items => items[0]);
+   * const price = item.discounted_price ?? item.price;
+   * const balance = {
+   *   points: profile.ach_points_balance,
+   *   gems: profile.ach_gems_balance,
+   *   diamonds: profile.ach_diamonds_balance,
+   * }[item.purchase_type];
+   * if (balance < price) {
+   *   console.log('[smartico] insufficient', item.purchase_type, '— disable Buy and show deficit', price - balance);
+   * }
    * ```
-   * **Visitor mode: not supported**
-   * */
+   */
   getUserProfile() {
     if (this.api.tracker) {
       const o = Object.assign({}, this.api.tracker.userPublicProps);
@@ -2437,74 +2536,850 @@ class WSAPI {
   async checkSegmentListMatch(segment_ids) {
     return await this.api.coreCheckSegments(this.userExtId, Array.isArray(segment_ids) ? segment_ids : [segment_ids]);
   }
-  /** Returns all the levels available to the current user
-   * **Example**:
-   * ```
-   * _smartico.api.getLevels().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getLevels().then((result) => {
-   *      console.log(result);
-   * });
+  /**
+   * Returns the full level ladder configured for the current label —
+   * one `TLevel` per active level, server-sorted by `required_points`
+   * ASC (lowest first; `ordinal_position` is a 1-based index into the
+   * returned array). Use this to render a level map / progression
+   * screen, or as a lookup table to resolve `ach_level_current_id` from
+   * {@link getUserProfile} into a richer level object.
+   *
+   * @remarks
+   * **Server-side filtering**
+   * The server returns ALL active levels for the label. There is NO
+   * per-user filtering on visibility, level-status, or anything else —
+   * the response is identical across users of the same label. Apply
+   * `visibility_points` filtering client-side if you want to hide
+   * not-yet-reached levels (compare against
+   * `getUserProfile().ach_points_ever` and exclude levels where
+   * `visibility_points > ach_points_ever`).
+   *
+   * **Sort order**
+   * The returned array is already sorted by `required_points` ASC, and
+   * `ordinal_position` is a 1-based index into that same sort order —
+   * client-side re-sorting is not required for the default rendering.
+   * If your label uses sliding-window leveling logic
+   * (see {@link getUserLevelExtraCounters}) and you want to sort by
+   * a multi-criteria key (`required_points`, then
+   * `required_level_counter_1`, then `required_level_counter_2`), do
+   * that client-side.
+   *
+   * **Cache TTL**: the SDK caches the response for 30 seconds. Cache
+   * is fully cleared on login / logout. Operator-driven level edits
+   * surface on the next cache miss.
+   *
+   * **Idempotency / Side effects**: safe. Read-only metadata. Calls
+   * within the cache window de-duplicate to the same cached array.
+   *
+   * **UI guidance**: see [UI Guide — `getLevels`](../../docs/ui/user/UIGuide_getLevels.md).
+   *
+   * **Visitor mode**: supported. Use `_smartico.vapi(lang).getLevels()`
+   * to fetch the ladder for anonymous viewers; the level configuration
+   * is label-scoped static data so the response is meaningful even
+   * without an authenticated user. Per-user fields (the implicit
+   * "current level" via {@link getCurrentLevel}, or the user's progress)
+   * are not available in visitor mode.
+   *
+   * @returns Promise resolving to the ordered `TLevel[]` ladder. Empty
+   *          if no levels are configured for the label.
+   *
+   * @example
+   * ```ts
+   * const [levels, profile] = await Promise.all([
+   *   window._smartico.api.getLevels(),
+   *   Promise.resolve(window._smartico.api.getUserProfile()),
+   * ]);
+   *
+   * // Resolve the user's current level by ID.
+   * const current = levels.find(l => l.id === profile.ach_level_current_id);
+   * console.log('[smartico] render header badge — current level:', current?.name,
+   *   '(position', current?.ordinal_position, 'of', levels.length, ')');
+   *
+   * // Filter to levels the user has unlocked enough to see.
+   * const visible = levels.filter(l =>
+   *   l.visibility_points == null || l.visibility_points <= profile.ach_points_ever
+   * );
+   * console.log('[smartico] render the level map with', visible.length, 'visible tiles');
+   *
+   * // Visitor-mode equivalent: returns the same ladder; no per-user state.
+   * // const visitorLevels = await window._smartico.vapi('EN').getLevels();
    * ```
    */
   async getLevels() {
     return OCache.use(onUpdateContextKey.Levels, ECacheContext.WSAPI, () => this.api.levelsGetT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Returns the current level of the user with extended information including ordinal position and progress.
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.getCurrentLevel().then((result) => {
-   *      console.log(result);
+   * Returns the user's current level — every `TLevel` field plus a
+   * computed `progress` percentage toward the next level. Use this to
+   * power a level badge with a progress bar.
+   *
+   * @remarks
+   * **How `progress` is computed**
+   * The SDK derives `progress` as the *delta-from-current-level-floor*:
+   * `(ach_points_ever − current.required_points) / (next.required_points
+   * − current.required_points) × 100`, clamped to `[0, 100]`. At the
+   * highest level (no next level), `progress` is `100`. Reading the
+   * source values directly from {@link getUserProfile}'s
+   * `ach_points_ever` and {@link getLevels} would also work, but
+   * `progress` saves the math.
+   *
+   * **Cache TTL**: the SDK caches the response for 30 seconds. There is
+   * no push event that refreshes this cache; a server-side level change
+   * (visible immediately on {@link getUserProfile}'s `ach_level_current_id`
+   * via the user-properties update channel) becomes visible on this
+   * method only after the cache TTL expires, or after
+   * `_smartico.api.clearCaches()` is called.
+   *
+   * **Leveling logic**
+   * The semantics of how a user advances depends on the label's
+   * leveling logic (configured per brand): points-only (the default),
+   * sliding-window with extra counters (uses
+   * {@link getUserLevelExtraCounters}), or fully-manual operator
+   * assignment. The `progress` percentage on this method assumes the
+   * points-only model — it's not meaningful for manual-only labels
+   * where level changes are operator-driven rather than points-driven.
+   *
+   * **Idempotency**: safe. Read-only. Repeated calls within the cache
+   * window return a deep-cloned cached value without a network
+   * round-trip.
+   *
+   * **Side effects**: none — pure read.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @returns Promise resolving to `TLevelCurrent` — the current level
+   *          plus `progress: number` (0–100).
+   *
+   * @example
+   * ```ts
+   * const level = await window._smartico.api.getCurrentLevel();
+   * console.log('[smartico] render level badge — name:', level.name,
+   *   'progress:', Math.round(level.progress), '%');
+   *
+   * // Detect level-up via getUserProfile's push channel.
+   * window._smartico.on('props_change', async (changed) => {
+   *   if ('ach_level_current_id' in changed) {
+   *     await window._smartico.api.clearCaches();   // bust the 30 s cache
+   *     const fresh = await window._smartico.api.getCurrentLevel();
+   *     console.log('[smartico] user levelled up — animate badge to new level:', fresh.name);
+   *   }
    * });
    * ```
-   *
-   * **Visitor mode: not supported**
    */
   async getCurrentLevel() {
     return OCache.use(onUpdateContextKey.CurrentLevel, ECacheContext.WSAPI, () => this.api.getLevelCurrent(this.userExtId), CACHE_DATA_SEC);
   }
-  /** Returns all the missions configured for the current user (server-side scoped, not filtered by Widget visibility).
-   * The returned missions are cached for 30 seconds. But you can pass the onUpdate callback as a parameter.
-   * Note that each time you call getMissions with a new onUpdate callback, the old one will be overwritten by the new one.
-   * The onUpdate callback will be called on mission OptIn and the updated missions will be passed to it.
+  /**
+   * Returns the user's current values for the two label-defined "extra
+   * counters" used by sliding-window leveling logic. Operators
+   * configure what each counter means per label (e.g. `level_counter_1`
+   * = total deposits in the last 30 days, `level_counter_2` = total
+   * wagering in the last 30 days). Compare against
+   * `required_level_counter_1` / `_2` on the next level from
+   * {@link getLevels} to know how close the user is to advancing.
+   *
+   * @remarks
+   * **When this matters**
+   * Only labels configured for sliding-window leveling populate the
+   * counter fields. On the default points-only leveling model, both
+   * `level_counter_1` and `level_counter_2` are `undefined`. Detect
+   * a points-only label by either counter being `undefined`.
+   *
+   * **Counter semantics — operator-defined**
+   * The SDK exposes raw numeric values; the meaning of each counter
+   * (deposit amount, wager amount, lifetime spend, etc.) is fully
+   * operator-defined per label. Resolve labels for display via
+   * {@link getTranslations} — the operator's display strings are
+   * stored under the translation keys `levelsCounter1Name` and
+   * `levelsCounter2Name`.
+   *
+   * **Refresh cadence**
+   * Sliding-window counters are recomputed by a server-side job that
+   * runs roughly every 60 seconds against the operator's BigQuery
+   * dataset; level transitions driven by counter changes have a
+   * latency of up to several minutes after the underlying activity
+   * (e.g. a deposit). The SDK caches the response for 30 seconds; no
+   * push event refreshes this cache. After a level change visible on
+   * {@link getUserProfile}'s `ach_level_current_id`, call
+   * `_smartico.api.clearCaches()` to force a fresh fetch.
+   *
+   * **Idempotency**: safe. Read-only. Repeated calls within the cache
+   * window return a deep-cloned cached value without a network
+   * round-trip.
+   *
+   * **Side effects**: none — pure read.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @returns Promise resolving to `UserLevelExtraCountersT`. Both
+   *          fields are `undefined` on labels not using sliding-window
+   *          leveling.
+   *
+   * @example
+   * ```ts
+   * const [counters, levels, profile] = await Promise.all([
+   *   window._smartico.api.getUserLevelExtraCounters(),
+   *   window._smartico.api.getLevels(),
+   *   Promise.resolve(window._smartico.api.getUserProfile()),
+   * ]);
+   *
+   * // Quick detection: undefined means this label doesn't use sliding-window leveling.
+   * if (counters.level_counter_1 === undefined) {
+   *   console.log('[smartico] points-only label — skip counter UI; show points progress only');
+   *   return;
+   * }
+   *
+   * // Find the next level and render a 3-bar progress block.
+   * const currentIdx = levels.findIndex(l => l.id === profile.ach_level_current_id);
+   * const next = levels[currentIdx + 1];
+   * if (next) {
+   *   console.log('[smartico] render points bar:', profile.ach_points_ever, '/', next.required_points);
+   *   if (next.required_level_counter_1) {
+   *     console.log('[smartico] render counter 1 bar:', counters.level_counter_1, '/', next.required_level_counter_1);
+   *   }
+   *   if (next.required_level_counter_2) {
+   *     console.log('[smartico] render counter 2 bar:', counters.level_counter_2, '/', next.required_level_counter_2);
+   *   }
+   * }
+   * ```
+   */
+  async getUserLevelExtraCounters() {
+    return OCache.use(onUpdateContextKey.LevelExtraCounters, ECacheContext.WSAPI, () => this.api.getUserGamificationInfoT(this.userExtId), CACHE_DATA_SEC);
+  }
+  /**
+   * Returns the activity log for a user within a specified time range.
+   * The response includes both points changes and gems/diamonds changes.
+   * Each log entry contains information about the change amount, balance, and source.
+   * The returned list is cached for 30 seconds.
+   * You can pass the onUpdate callback as a parameter, it will be called every time the activity log is updated and will provide the updated list of activity logs for the last 10 minutes.
    *
    * **Example**:
    * ```
-   * _smartico.api.getMissions().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * const startTime = Math.floor(Date.now() / 1000) - 86400 * 30; // 30 days ago
+   * const endTime = Math.floor(Date.now() / 1000); // now
    *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getMissions().then((result) => {
+   * _smartico.api.getActivityLog({
+   *      startTimeSeconds: startTime,
+   *      endTimeSeconds: endTime,
+   *      from: 0,
+   *      to: 50,
+   *      onUpdate: (data) => console.log('Updated:', data)
+   * }).then((result) => {
    *      console.log(result);
    * });
    * ```
+   *
+   * **Visitor mode: not supported**
+   *
+   * @param params - Activity log parameters
+   * @param params.startTimeSeconds - Start time in seconds (epoch timestamp)
+   * @param params.endTimeSeconds - End time in seconds (epoch timestamp)
+   * @param params.from - Start index of records to return
+   * @param params.to - End index of records to return
+   * @param params.onUpdate - Optional callback function that will be called when the activity log is updated
    */
-  async getMissions({
+  async getActivityLog({
+    startTimeSeconds,
+    endTimeSeconds,
+    from,
+    to,
     onUpdate
-  } = {}) {
+  }) {
     if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.Missions, onUpdate);
+      this.onUpdateCallback.set(onUpdateContextKey.ActivityLog, onUpdate);
     }
-    return OCache.use(onUpdateContextKey.Missions, ECacheContext.WSAPI, () => this.api.missionsGetItemsT(this.userExtId), CACHE_DATA_SEC);
+    return await OCache.use(onUpdateContextKey.ActivityLog, ECacheContext.WSAPI, () => this.api.getActivityLogT(this.userExtId, startTimeSeconds, endTimeSeconds, from, to), CACHE_DATA_SEC);
+  }
+  async notifyActivityLogUpdate() {
+    const startSeconds = Date.now() / 1000 - 600;
+    const endSeconds = Date.now() / 1000;
+    const payload = await this.api.getActivityLogT(this.userExtId, startSeconds, endSeconds, 0, 50);
+    this.updateEntity(onUpdateContextKey.ActivityLog, payload);
+  }
+}
+
+/** @group General */
+class WSAPIGeneral extends WSAPIUser {
+  async getCustomSections() {
+    return OCache.use(onUpdateContextKey.CustomSections, ECacheContext.WSAPI, () => this.api.customSectionsGetT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Returns all the badges available to the current user
-   *
-   * **Visitor mode: not supported**
+   * Requests translations for the given language. Returns the object including translation key/translation value pairs. All possible translation keys defined in the back office.
+   */
+  async getTranslations(lang_code) {
+    const r = await this.api.getTranslationsT(this.userExtId, lang_code, []);
+    return {
+      translations: r.translations
+    };
+  }
+  /**
+   * Returns all the related tournaments and missions for the provided game id for the current user
+   * The provided Game ID should correspond to the ID from the Games Catalog - https://help.smartico.ai/welcome/technical-guides/games-catalog-api
+   *
+   * **Example**:
+   * ```
+   * _smartico.api.getRelatedItemsForGame('gold-slot2').then((result) => {
+   *      console.log(result);
+   * });
+   * ```
+   *
+   * **Example in the Visitor mode**:
+   * ```
+   * _smartico.vapi('EN').getRelatedItemsForGame('gold-slot2').then((result) => {
+   *      console.log(result);
+   * });
+   * ```
+   */
+  async getRelatedItemsForGame(related_game_id) {
+    const result = await this.api.getRelatedItemsForGame(this.userExtId, related_game_id);
+    return result;
+  }
+}
+
+/** @group Missions */
+class WSAPIMissions extends WSAPIGeneral {
+  /**
+   * Returns all missions visible to the current user, scoped server-side
+   * to what the user is qualified to see. Optionally subscribes to live
+   * updates via `onUpdate`: the callback is invoked with the full, refreshed
+   * mission array whenever the server pushes a mission-state-changing event.
+   *
+   * The returned list is the canonical source of truth for mission state
+   * (`is_opted_in`, `progress`, `is_completed`, `completion_count`, etc.).
+   * Consumers should NEVER mutate it optimistically — always wait for the
+   * `onUpdate` callback (or a fresh `getMissions()` call after the 30s cache
+   * window expires) to observe the new state.
+   *
+   * @remarks
+   * **Subscription model (`onUpdate`)**
+   * The callback receives the FULL refreshed mission array (never a
+   * diff/patch). Each subsequent call to `getMissions({ onUpdate })`
+   * REPLACES the prior callback — only one active subscriber at a time.
+   * Pass `onUpdate: undefined` (or omit it) to keep the prior callback in
+   * place; the callback is never auto-cleared.
+   *
+   * **Update triggers** — the callback fires when:
+   * 1. **Mutation responses**: `requestMissionOptIn(...)` or
+   *    `requestMissionClaimReward(...)` resolves (any `err_code`).
+   * 2. **Asynchronous server pushes**: a user activity (deposit, bet,
+   *    login, etc.) advances task progress on a task configured to push
+   *    updates, or completes a mission.
+   * 3. **Visibility changes**: the user's level changes, or other
+   *    gamification visibility tags change.
+   *
+   * Operator-side BO mission-config edits do NOT push to connected
+   * clients — those changes surface only on the next cache miss (after
+   * the 30 s TTL) or alongside the next trigger from (1)–(3).
+   *
+   * **What's in the returned list / what's filtered server-side**
+   * The response is pre-filtered by the server. Missions EXCLUDED before
+   * reaching the SDK:
+   * - Missions in `DRAFT` or `ARCHIVED` status (see {@link AchievementStatus}).
+   * - Missions where the user fails visibility conditions. Exception:
+   *   completed missions may remain visible after the user no longer
+   *   qualifies (configurable per-brand).
+   * - `FEATURED_MANUALLY` missions that are still locked — they appear
+   *   only after the user unlocks them.
+   * - Locked missions configured to hide while locked — UNLESS the
+   *   mission is configured to expose immediately on unlock (then the
+   *   locked mission is included as a teaser).
+   * - `RECURRING` missions between cycles, until the next cycle starts.
+   * - `RECURRING_QUANTITY` missions outside their `active_from_ts` /
+   *   `active_till_ts` window.
+   *
+   * Client-side filtering you may still want: missions with
+   * `only_in_custom_section: true` are intended for their custom-section
+   * view only and should be hidden from the main mission list.
+   *
+   * **Reading state from the returned mission**
+   * Drive availability chips ("missed", "coming soon", "needs opt-in",
+   * "in progress", "expired") from `availability_status` (enum
+   * {@link AchievementAvailabilityStatus}) — it's the canonical derived
+   * state and reflects all server-side timing/visibility rules in one
+   * field. For time-limited and recurring missions, `dt_start` doubles
+   * as the opt-in timestamp (for opt-in missions) or unlock timestamp
+   * (for previously-locked missions); the expiration of a time-limited
+   * mission is `dt_start + time_limit_ms`. `next_recurrence_date_ts`
+   * is populated for `RECURRING` / `RECURRING_QUANTITY` missions but
+   * is no longer meaningful once the mission's `active_till_ts` has
+   * passed.
+   *
+   * **Refresh after a mutation**
+   * After `requestMissionOptIn(...)` or `requestMissionClaimReward(...)`
+   * resolves, the SDK auto-refreshes the mission cache; the `onUpdate`
+   * callback fires with the new array shortly after. `is_opted_in`,
+   * `progress`, and `is_completed` flip on the refreshed mission — do
+   * NOT mutate them optimistically while the round-trip is pending.
+   * Render any pending state from your own loading flag.
+   *
+   * **UI guidance**: see [UI Guide — `getMissions`](../../docs/ui/missions/UIGuide_getMissions.md).
+   *
+   * @param params              Optional. Omit to fetch without subscribing.
+   * @param params.onUpdate     Callback invoked with the full refreshed
+   *                            mission array on every server-pushed update
+   *                            (after opt-in / claim-reward calls, or when
+   *                            the server pushes an asynchronous
+   *                            mission-state change). Each call to
+   *                            `getMissions` overwrites the prior callback.
+   *                            Never fires in visitor mode.
+   * @returns                   Promise resolving to the current list of
+   *                            missions visible to the user. Empty array if
+   *                            the user has no missions (or if the visitor
+   *                            proxy user has none configured).
+   *
+   * @example
+   * ```ts
+   * // 1. Initial fetch + subscribe to live updates
+   * const missions = await window._smartico.api.getMissions({
+   *   onUpdate: (refreshed) => {
+   *     console.log('[smartico] mission list refreshed — re-render the entire mission list UI from this array, do not merge with prior state:', refreshed);
+   *
+   *     // 2. onUpdate fires for: opt-in/claim responses, task-progress
+   *     //    pushes that complete a mission or move a "pushToClient" task,
+   *     //    and user-level changes. Treat each call as authoritative.
+   *     const claimable = refreshed.filter(m =>
+   *       m.is_completed && m.requires_prize_claim && !m.prize_claimed_date_ts,
+   *     );
+   *     if (claimable.length > 0) {
+   *       console.log('[smartico] there are unclaimed mission prizes — surface a "Claim" CTA on each of these missions:', claimable.map(m => m.id));
+   *     }
+   *   },
+   * });
+   *
+   * // 3. Filter/render from the returned list. The server already excludes
+   * //    DRAFT/ARCHIVED missions and ones the user can't see. You may need
+   * //    client-side filters for view-specific concerns (custom sections,
+   * //    completed/missed tabs).
+   * const generalView = missions
+   *   .filter(m => !m.only_in_custom_section)
+   *   .sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+   *
+   * console.log('[smartico] initial mission list ready — render', generalView.length, 'missions sorted by position');
+   *
+   * // 4. Visitor-mode equivalent: onUpdate is accepted but never fires.
+   * //    Re-poll if you need fresh data.
+   * // const visitorMissions = await window._smartico.vapi('EN').getMissions();
+   * // console.log('[smartico] visitor missions are the brand proxy user\'s — per-user fields are not meaningful');
+   * ```
+   */
+  async getMissions({
+    onUpdate
+  } = {}) {
+    if (onUpdate) {
+      this.onUpdateCallback.set(onUpdateContextKey.Missions, onUpdate);
+    }
+    return OCache.use(onUpdateContextKey.Missions, ECacheContext.WSAPI, () => this.api.missionsGetItemsT(this.userExtId), CACHE_DATA_SEC);
+  }
+  /**
+   * Returns all the badges available to the current user.
+   *
+   * Badges are completion-tracked achievements that auto-unlock once the user
+   * meets their criteria — there is no opt-in step, no claim step, and no
+   * task-description reveal. Contrast with {@link getMissions}, which returns
+   * the same `TMissionOrBadge[]` shape but represents explicit opt-in flows.
+   *
+   * @remarks
+   * **Why no `onUpdate` callback?**
+   * Unlike `getMissions({ onUpdate })`, this method does NOT accept an
+   * `onUpdate` subscription. Internally the SDK never refreshes the `Badges`
+   * cache from server pushes: the achievement-related push events
+   * (mission opt-in / claim / reload) refresh the missions cache, NOT
+   * the badges cache. The badges cache is flushed only by:
+   * - its 30-second TTL
+   * - a full SDK cache wipe at login / logout
+   *
+   * **How to refresh the badge list**
+   * If you need near-live badge state, poll manually after the TTL expires.
+   * The first call inside the 30 s window returns the cached payload; the
+   * first call after the TTL triggers a fresh server round-trip. Example:
+   * ```ts
+   * setInterval(async () => {
+   *   const badges = await window._smartico.api.getBadges();
+   *   console.log('[smartico] badge list polled — re-render badge grid from this array', badges);
+   * }, 30_000);
+   * ```
+   * Alternatively, re-fetch on a domain event your app already handles
+   * (e.g. after the user finishes a game round or claims a bonus).
+   *
+   * **Differences from missions** (same `TMissionOrBadge` shape, different
+   * feature)
+   * The opt-in, claim, recurring-cycle, and unlock-description fields on
+   * the returned objects are not populated for badges; treat their values
+   * as undefined / default. Time windows are absolute calendar timestamps
+   * (`active_from_ts` / `active_till_ts`), not opt-in-relative durations —
+   * drive availability chips from the SDK-computed `badgeTimeLimitState`
+   * (enum {@link BadgesTimeLimitStates}), not `time_limit_ms`. Locking for
+   * badges is purely time-based: `is_locked` is `true` only when
+   * `badgeTimeLimitState === BadgesTimeLimitStates.BeforeStartDate` (the
+   * time window hasn't started yet). The primary navigation field is
+   * `category_ids` — call {@link getAchCategories} to resolve category
+   * metadata and group badges by category.
+   *
+   * **Idempotency / Side effects**: fetch-only; safe to call repeatedly.
+   * The cache layer deduplicates concurrent calls within the TTL window.
+   *
+   * **UI guidance**: see [UI Guide — `getBadges`](../../docs/ui/missions/UIGuide_getBadges.md).
+   *
+   * @returns Promise resolving to `TMissionOrBadge[]`. Every item has
+   *          `type === 'badge'`. Cached for 30 s under the `Badges` key.
+   *
+   * @example
+   * ```ts
+   * const [badges, categories] = await Promise.all([
+   *   window._smartico.api.getBadges(),
+   *   window._smartico.api.getAchCategories(),
+   * ]);
+   *
+   * console.log('[smartico] badges fetched — render grouped grid with', badges.length, 'badges across', categories.length, 'categories');
+   *
+   * for (const category of categories) {
+   *   const inCategory = badges.filter(b => b.category_ids?.includes(category.id));
+   *   const completed = inCategory.filter(b => b.is_completed).length;
+   *   console.log(`[smartico] render category section "${category.name}" header showing ${completed}/${inCategory.length}`);
+   *
+   *   for (const badge of inCategory) {
+   *     // Use badgeTimeLimitState (not time_limit_ms) for availability chip
+   *     if (badge.badgeTimeLimitState === 0) { // BadgesTimeLimitStates.BeforeStartDate
+   *       console.log('[smartico] badge not yet started — render grayscaled card with "Starts on" chip for badge', badge.id);
+   *     } else if (badge.is_completed) {
+   *       console.log('[smartico] badge completed — render with completed styling and check-mark for badge', badge.id);
+   *     } else {
+   *       console.log('[smartico] badge in progress — render with stage counter (completed_tasks / total) for badge', badge.id);
+   *     }
+   *   }
+   * }
+   *
+   * // No onUpdate available — poll if live state matters
+   * setInterval(async () => {
+   *   try {
+   *     const fresh = await window._smartico.api.getBadges();
+   *     console.log('[smartico] badge poll tick — diff against previous list and re-render any changed badge cards', fresh);
+   *   } catch (e) {
+   *     console.error('[smartico] badge poll failed — keep showing last known state, retry on next tick:', e);
+   *   }
+   * }, 30_000);
+   * ```
    */
   async getBadges() {
     return OCache.use(onUpdateContextKey.Badges, ECacheContext.WSAPI, () => this.api.badgetsGetItemsT(this.userExtId), CACHE_DATA_SEC);
   }
+  /**
+   * Returns the list of active mission/badge categories configured for the current label.
+   * Categories are operator-defined groupings used to organize missions and badges into
+   * sections, tabs, or filter chips in the gamification UI. The same category list serves
+   * BOTH missions and badges — there is no separate "mission categories" vs "badge
+   * categories" split on the server.
+   *
+   * @remarks
+   * **What categories are**
+   * - Operator-defined groupings, configured per-label by the brand operator.
+   *   Only active categories are returned; inactive/deleted ones are filtered out.
+   * - Each `TAchCategory` exposes `{ id, name, order }`. `name` is the display label;
+   *   `order` is the relative position (lower = appears first).
+   * - The same array covers BOTH missions and badges — categories are not filtered by
+   *   entity type on the server.
+   *
+   * **Localization / translation**
+   * - `name` is **pre-translated server-side** to the authenticated user's stored language.
+   *   In visitor mode, the language passed to `_smartico.vapi(lang)` drives the
+   *   translation. Consumers never need to translate `name` themselves.
+   * - Fallback if no translation exists for the user's language: the brand's EN value
+   *   is returned. The field is never null.
+   *
+   * **Sort order**
+   * The server does NOT pre-sort. Sort client-side before rendering:
+   * `categories.sort((a, b) => a.order - b.order)`.
+   *
+   * **How missions/badges join to categories**
+   * Each `TMissionOrBadge` exposes `category_ids: number[]` (zero-or-more,
+   * many-to-many). A single mission/badge can belong to multiple categories
+   * simultaneously, or to none. To render a "category → items" view:
+   * `missions.filter(m => m.category_ids.includes(cat.id))`.
+   *
+   * **Uncategorized items**
+   * Items with `category_ids: []` are NOT represented by a synthetic "Other" entry.
+   * If your UI needs one, generate it client-side by checking
+   * `item.category_ids.length === 0`.
+   *
+   * **Empty categories**
+   * A category may be returned even if zero missions/badges reference it. Filter
+   * out empty categories on the consumer side if you don't want to render section
+   * headers for them.
+   *
+   * **Refresh cadence / cache**
+   * - The SDK caches the response for 30 seconds. Subsequent calls within that
+   *   window return the cached array without a network round-trip.
+   * - The cache is NOT invalidated by mission/badge push events — operator-driven
+   *   category changes propagate at the next 30 s cache miss.
+   * - Cache is fully cleared on login / logout.
+   * - In **visitor mode** additional server-side caching applies on top of the
+   *   SDK cache; worst-case staleness for an edited/added category is on the order
+   *   of a few minutes for anonymous viewers.
+   *
+   * **Idempotency**: safe. Read-only metadata fetch. Cache de-duplicates concurrent calls.
+   *
+   * **Side effects**: none — pure metadata read.
+   *
+   * **UI guidance**: see [UI Guide — `getAchCategories`](../../docs/ui/missions/UIGuide_getAchCategories.md).
+   *
+   * @returns Array of `{ id, name, order }`. Empty array if no active categories are
+   *   configured for the label. `name` is pre-translated. Order is NOT applied — caller
+   *   must sort.
+   *
+   * @example
+   * ```ts
+   * const categories = await window._smartico.api.getAchCategories();
+   *
+   * if (categories.length === 0) {
+   *   console.log('[smartico] no categories configured — render missions/badges as a flat list without section headers');
+   * } else {
+   *   const sorted = [...categories].sort((a, b) => a.order - b.order);
+   *   console.log('[smartico] categories loaded — render one tab/section per entry in this order:', sorted.map(c => c.name));
+   *
+   *   // Join to missions: render each category as a section
+   *   const missions = await window._smartico.api.getMissions();
+   *   for (const cat of sorted) {
+   *     const items = missions.filter(m => m.category_ids.includes(cat.id));
+   *     if (items.length === 0) {
+   *       console.log('[smartico] category has no missions — skip rendering its section header:', cat.name);
+   *       continue;
+   *     }
+   *     console.log(`[smartico] render section "${cat.name}" with ${items.length} mission(s)`);
+   *   }
+   *
+   *   // Uncategorized items: surface in a caller-provided "Other" bucket if needed
+   *   const uncategorized = missions.filter(m => m.category_ids.length === 0);
+   *   if (uncategorized.length > 0) {
+   *     console.log('[smartico] uncategorized missions exist — render a caller-provided "Other" section; server does NOT return id:-1:', uncategorized.length);
+   *   }
+   * }
+   *
+   * // Visitor mode — same shape, language driven by vapi(lang) argument
+   * const visitorCats = await window._smartico.vapi('DE').getAchCategories();
+   * console.log('[smartico] visitor-mode categories (names translated to DE):', visitorCats);
+   * ```
+   */
+  async getAchCategories() {
+    return OCache.use(onUpdateContextKey.AchCategories, ECacheContext.WSAPI, () => this.api.achGetCategoriesT(this.userExtId), CACHE_DATA_SEC);
+  }
+  /**
+   * Opt the current user in to a mission. The mission must have
+   * `is_requires_optin: true` (from `getMissions()`) and must not already
+   * be opted-in or locked. After a successful opt-in, the user's task
+   * progress starts counting toward this mission — events fired BEFORE
+   * opt-in do not count retroactively (except `UNLOCK_ACHIEVEMENT` tasks,
+   * which are exempt and can fire pre-opt-in).
+   *
+   * @remarks
+   * **Preconditions**
+   * Only call when the mission has `is_requires_optin === true`,
+   * `is_opted_in === false`, and `is_locked === false`. Calling on a
+   * mission that does not require opt-in is wasted; calling twice returns
+   * `40010`.
+   *
+   * **Error codes** (in `err_code`)
+   * - `0` — success; task progress counting begins
+   * - `105` — wrong mission id (different label) OR visibility conditions
+   *   not met. Same code covers both; use `err_message` to disambiguate.
+   * - `40010` — already opted-in. Safe to treat as "no-op success"; usually
+   *   means local mission state was stale (e.g. user opted in from another
+   *   session/tab).
+   * - `40013` — mission not opt-in-able: missing `requires_optin`, in
+   *   DRAFT/ARCHIVED state, or outside its `active_from_ts` /
+   *   `active_till_ts` window.
+   * - `40014` — mission is locked; user has unlock-tasks remaining.
+   *   Surface the mission's `unlock_mission_description` to guide them.
+   * - other non-zero — generic server error. Surface `err_message` if any.
+   *
+   * **Time-limited missions**
+   * For missions with `time_limit_ms > 0`, the countdown begins at opt-in
+   * time, not at mission creation. Server records expiration as
+   * `optin_date + time_limit_ms`.
+   *
+   * **Refresh after success**
+   * The SDK refreshes its mission cache automatically on opt-in response;
+   * any `onUpdate` callback passed to a prior `getMissions({ onUpdate })`
+   * fires with the new state shortly after. No manual re-fetch needed.
+   *
+   * **Idempotency**: not idempotent. A second call returns `40010`. Guard
+   * the call site against double-clicks.
+   *
+   * **Side effects**: does NOT award points / badges / levels directly.
+   * Rewards come from task completion, which is itself gated on opt-in.
+   * May affect visibility of other missions whose visibility conditions
+   * depend on this opt-in.
+   *
+   * **UI guidance**: see [UI Guide — `requestMissionOptIn`](../../docs/ui/missions/UIGuide_requestMissionOptIn.md).
+   *
+   * **Visitor mode: not supported**
+   *
+   * @param mission_id  The mission `id` (from `getMissions()`)
+   * @returns `{ err_code, err_message }`; success when `err_code === 0`
+   *
+   * @example
+   * ```ts
+   * const missions = await window._smartico.api.getMissions({
+   *   onUpdate: (m) => console.log('[smartico] mission list updated — re-render mission UI from this new array', m),
+   * });
+   * const mission = missions.find(m => m.id === missionId);
+   *
+   * if (!mission || !mission.is_requires_optin || mission.is_opted_in || mission.is_locked) {
+   *   console.log('[smartico] opt-in not applicable — keep UI as-is');
+   *   return;
+   * }
+   *
+   * console.log('[smartico] opt-in starting — show loading spinner on opt-in button and disable it to prevent double-clicks');
+   * const r = await window._smartico.api.requestMissionOptIn(mission.id);
+   * console.log('[smartico] opt-in response received — clear loading spinner');
+   *
+   * if (r.err_code === 0 || r.err_code === 40010) {
+   *   console.log('[smartico] opt-in succeeded (or was already done) — onUpdate above will fire with refreshed mission state; no manual re-fetch needed');
+   * } else if (r.err_code === 40014) {
+   *   console.error('[smartico] mission is locked — surface the unlock description as guidance:', mission.unlock_mission_description);
+   * } else {
+   *   console.error('[smartico] opt-in failed — show an error toast with this message to the user:', r.err_message);
+   * }
+   * ```
+   */
+  async requestMissionOptIn(mission_id) {
+    const r = await this.api.missionOptIn(this.userExtId, mission_id);
+    const o = {
+      err_code: r.errCode,
+      err_message: r.errMsg
+    };
+    return o;
+  }
+  /**
+   * Claim the prize for a completed mission. This is the step that runs
+   * AFTER `requestMissionOptIn()` (when applicable) and AFTER the user has
+   * completed all of the mission's tasks. Only call when the mission has
+   * `requires_prize_claim === true`, `is_completed === true`, and the prize
+   * has not already been claimed.
+   *
+   * The points / bonuses / badge grants associated with the mission are
+   * awarded server-side synchronously inside this call (before the response
+   * is returned), so a successful response (`err_code === 0`) means the
+   * reward has already landed in the user's account.
+   *
+   * @remarks
+   * **Preconditions**
+   * Only call when, on the mission object from `getMissions()`:
+   * - `is_completed === true`
+   * - `requires_prize_claim === true`
+   * - `prize_claimed_date_ts == null` (i.e. not already claimed)
+   * - `prize_claim_expiration_date` is `null` OR still in the future
+   *
+   * The `ach_completed_id` argument must be passed straight from the same
+   * mission object (`mission.ach_completed_id`). It is a server-side primary
+   * key identifying the specific completion row; the SDK consumer should
+   * never synthesise or cache it across sessions — always re-read it from a
+   * fresh `getMissions()` result.
+   *
+   * **Error codes** (in `err_code`)
+   * - `0` — success; the prize was claimed and rewards have been credited.
+   * - `1` — generic server error. Covers several distinct underlying
+   *   conditions, all collapsed into the same code: stale or wrong
+   *   `ach_completed_id` (does not match user / mission), the mission no
+   *   longer requiring a prize claim, the mission being archived/draft,
+   *   label mismatch, or the completion being too old (server enforces a
+   *   freshness window of several months). Recovery: re-fetch missions
+   *   with `getMissions()`; if the mission still appears claimable,
+   *   surface a generic error.
+   * - `40015` — claim window expired (`prize_claim_expiration_date` has
+   *   passed). Show a "claim period ended" message; do not retry.
+   * - `40016` — mission is not completed yet. Indicates a race or a stale
+   *   local cache. Re-fetch via `getMissions()`; if `is_completed` is still
+   *   false, the UI should hide the claim button.
+   * - `40017` — prize already claimed. Treat as idempotent success: refresh
+   *   the mission list (auto-refresh will fire) and hide the claim button.
+   *   Usually means another tab/session already claimed it.
+   * - other non-zero — generic server error. Surface `err_message` if any.
+   *
+   * **Recurring missions**
+   * The server transparently handles both one-shot and recurring mission
+   * completions. The SDK consumer passes a single `ach_completed_id`
+   * regardless of mission type; the server resolves the correct completion.
+   *
+   * **Refresh after success**
+   * On any claim response (success OR failure), the SDK automatically
+   * re-fetches the mission list and fires any `onUpdate` callback
+   * registered via `getMissions({ onUpdate })`. No manual re-fetch needed.
+   * Note: points balance, badges, and level state arrive through their
+   * own push channels — subscribe to them separately if your UI shows
+   * those values.
+   *
+   * **Idempotency**: not idempotent at the row level. A second call on the
+   * same `ach_completed_id` returns `40017` (already claimed). For a stale
+   * `ach_completed_id` the second call returns `1`. Guard the call site
+   * against double-clicks; the SDK does not enforce its own in-flight lock.
+   *
+   * **Side effects** (consumer-observable effects of a successful claim):
+   * - Points credited to the user's balance.
+   * - CRM-rule activities executed (may grant bonuses, badges; may unlock
+   *   follow-up missions, which arrive as a later mission auto-refresh).
+   * - Analytics / automation events fired downstream; not directly observable
+   *   in the response, but visible via the mission auto-refresh and any
+   *   subsequent bonus / badge updates.
+   *
+   * **UI guidance**: see [UI Guide — `requestMissionClaimReward`](../../docs/ui/missions/UIGuide_requestMissionClaimReward.md).
+   *
+   * @param mission_id        The mission `ach_id` (from `getMissions()`).
+   * @param ach_completed_id  The completion-row identifier, read from
+   *                          `mission.ach_completed_id` on the same mission
+   *                          object fetched via `getMissions()`. Never
+   *                          fabricate or cache across sessions.
+   * @returns `{ err_code, err_message }`; success when `err_code === 0`
+   *          (or `40017` when treated as idempotent no-op).
+   *
+   * @example
+   * ```ts
+   * const missions = await window._smartico.api.getMissions({
+   *   onUpdate: (m) => console.log('[smartico] mission list updated — re-render mission UI from this new array', m),
+   * });
+   * const mission = missions.find(m => m.ach_id === missionId);
+   *
+   * if (
+   *   !mission ||
+   *   !mission.is_completed ||
+   *   !mission.requires_prize_claim ||
+   *   mission.prize_claimed_date_ts ||
+   *   (mission.prize_claim_expiration_date && Date.now() >= mission.prize_claim_expiration_date)
+   * ) {
+   *   console.log('[smartico] claim not applicable — keep claim button hidden');
+   *   return;
+   * }
+   *
+   * console.log('[smartico] claim starting — show loading spinner on claim button and disable it to prevent double-clicks');
+   * const r = await window._smartico.api.requestMissionClaimReward(mission.ach_id, mission.ach_completed_id);
+   * console.log('[smartico] claim response received — clear loading spinner');
+   *
+   * if (r.err_code === 0 || r.err_code === 40017) {
+   *   console.log('[smartico] claim succeeded (or was already claimed) — points/bonuses are credited; mission list auto-refresh will fire via the onUpdate above; hide the claim button');
+   * } else if (r.err_code === 40015) {
+   *   console.error('[smartico] claim window expired — show a "claim period ended" message and remove the claim button:', mission.prize_claim_expiration_date);
+   * } else if (r.err_code === 40016) {
+   *   console.error('[smartico] mission reported as not completed by server — local state was stale; auto-refresh will reconcile, do not retry');
+   * } else {
+   *   console.error('[smartico] claim failed — show an error toast with this message to the user (and re-fetch missions to recover from a stale ach_completed_id):', r.err_message);
+   * }
+   * ```
+   */
+  async requestMissionClaimReward(mission_id, ach_completed_id) {
+    const r = await this.api.missionClaimPrize(this.userExtId, mission_id, ach_completed_id);
+    const o = {
+      err_code: r.errCode,
+      err_message: r.errMsg
+    };
+    return o;
+  }
+  async updateMissions() {
+    const payload = await this.api.missionsGetItemsT(this.userExtId);
+    this.updateEntity(onUpdateContextKey.Missions, payload);
+  }
+}
+
+/** @group Bonuses */
+class WSAPIBonuses extends WSAPIMissions {
   /**
    * Returns all the bonuses for the current user
    * The returned bonuses are cached for 30 seconds. But you can pass the onUpdate callback as a parameter.
@@ -2538,45 +3413,198 @@ class WSAPI {
     };
     return o;
   }
-  /**
-   * Returns the extra counters for the current user level.
-   * These are counters that are configured for each Smartico client separately by request.
-   * For example 1st counter could be total wagering amount, 2nd counter could be total deposit amount, etc.
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.getUserLevelExtraCounters().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *
-   * **Visitor mode: not supported**
-   */
-  async getUserLevelExtraCounters() {
-    return OCache.use(onUpdateContextKey.LevelExtraCounters, ECacheContext.WSAPI, () => this.api.getUserGamificationInfoT(this.userExtId), CACHE_DATA_SEC);
+  async updateBonuses() {
+    const payload = await this.api.bonusesGetItemsT(this.userExtId);
+    this.updateEntity(onUpdateContextKey.Bonuses, payload);
+  }
+}
+
+/** @group Store */
+class WSAPIStore extends WSAPIBonuses {
+  constructor(...args) {
+    super(...args);
+    this.storeHistoryOnUpdateParams = {
+      limit: 20,
+      offset: 0
+    };
+  }
+  storeHistoryCacheKey(limit, offset) {
+    return `${onUpdateContextKey.StoreHistory}:${limit}:${offset}`;
   }
   /**
-   *
-   * Returns all the store items available to the current user
-   * The returned store items are cached for 30 seconds. But you can pass the onUpdate callback as a parameter.
-   * Note that each time you call getStoreItems with a new onUpdate callback, the old one will be overwritten by the new one.
-   * The onUpdate callback will be called on purchase of the store item.
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.getStoreItems().then((result) => {
-   *      console.log(result);
+   * Returns the catalog of buyable store items visible to the current user,
+   * scoped server-side to what the user is qualified to see. Optionally
+   * subscribes to live updates via `onUpdate`: the callback is invoked with
+   * the full refreshed catalog after every purchase the user makes from this
+   * device.
+   *
+   * The returned list is the canonical source of truth for store state
+   * (`can_buy`, `pool`, `discounted_price`, `active_till_date`, etc.).
+   * Consumers should NEVER mutate it optimistically — always re-fetch (or
+   * wait for the `onUpdate` callback) to observe the new state.
+   *
+   * @remarks
+   * **Preconditions**
+   * The catalog is per-user. Visitor mode is supported with caveats (see
+   * "Visitor mode" below). For the authenticated path, the user's balances
+   * (`ach_points_balance`, `ach_gems_balance`, `ach_diamonds_balance` from
+   * {@link getUserProfile}) must be tracked client-side to drive the
+   * affordability state of the Buy button — the SDK does not pre-compute
+   * affordability into `can_buy`.
+   *
+   * **Subscription model (`onUpdate`)**
+   * The callback receives the FULL refreshed catalog (never a diff/patch).
+   * Each subsequent call to `getStoreItems({ onUpdate })` REPLACES the prior
+   * callback — only one active subscriber at a time. Pass
+   * `onUpdate: undefined` (or omit it) to keep the prior callback in place;
+   * the callback is never auto-cleared.
+   *
+   * **Update triggers**
+   *
+   * Fires after: any `buyStoreItem(...)` call resolves on this connection
+   * (success OR failure). This is the ONLY trigger. The refreshed array
+   * reflects pool decrement on the just-bought item, per-period purchase
+   * cap re-evaluation on `can_buy`, and any `purchased_today` /
+   * `purchased_this_week` / `purchased_this_month` flips visible via
+   * {@link getStorePurchasedItems}.
+   *
+   * Does NOT fire for:
+   * - Operator-side BO catalog edits (price, ribbons, pool seed, segment
+   *   conditions, new/removed items) — surface only on the next cache miss.
+   * - Concurrent purchases by OTHER users — the current user's view of
+   *   `pool` may be stale until they themselves refresh.
+   * - User balance changes from gameplay — the catalog is independent of
+   *   balance; the consumer drives Buy-button affordability from a
+   *   separately-tracked balance source.
+   * - Items going past their `active_till_date` while the page is open —
+   *   the item simply disappears on the next refresh.
+   *
+   * **Server-side filtering** (what's already excluded before the SDK sees it)
+   * - Items outside the `[active_from_date, active_till_date]` window —
+   *   past the till-date, items are ALWAYS filtered out server-side.
+   * - Items the user fails visibility-segment / visibility-condition
+   *   checks for.
+   * - Items configured to hide-when-empty whose pool has reached 0
+   *   (per-item operator flag). Items without that flag are still returned
+   *   with `pool === 0` so a "Sold out" state can be rendered.
+   * - Items where the per-period bought-count cap is reached (and the
+   *   operator chose to hide rather than just disable).
+   *
+   * **Reading state from the returned item**
+   * The catalog row carries everything a Buy button needs except the user's
+   * balance: `can_buy` already reflects segment / visibility / per-period
+   * cap checks, but the SDK does NOT pre-compute balance affordability —
+   * compare `discounted_price ?? price` against the user's balance for
+   * `purchase_type` (`ach_points_balance` / `ach_gems_balance` /
+   * `ach_diamonds_balance` from {@link getUserProfile}). `purchase_type` is
+   * per-item (`'points'` / `'gems'` / `'diamonds'`); operators can mix
+   * currencies within a single catalog. For sold-out display, `pool === 0`
+   * means the operator chose to keep the item visible — render an "Out of
+   * stock" overlay. When `discounted_price` is set, render `price` with a
+   * strikethrough and `discounted_price` as the active price; the
+   * accompanying `discount_price_ribbon` is either a percentage preset
+   * (`'10'`, `'15'`, `'20'`, `'25'`, `'50'`) or the literal `'custom'`
+   * (in which case `custom_ribbon_image` is the artwork at 250×300 px).
+   * A live countdown for time-limited items is rendered only when the
+   * operator has enabled the per-item `show_timer` flag.
+   *
+   * **Cross-references**
+   * `category_ids` joins to `TStoreCategory.id` from
+   * {@link getStoreCategories} (many-to-many — an item can belong to
+   * multiple categories). Items with `only_in_custom_section: true` are
+   * returned in the catalog but intended for their custom-section view
+   * only — filter them client-side for the main store view. The
+   * history-only fields (`purchase_ts`, `purchase_points_amount`, the
+   * `purchased_*` booleans) are populated only by
+   * {@link getStorePurchasedItems}, not by this method.
+   *
+   * **Idempotency**: yes. `getStoreItems` is a pure read. Calling it
+   * repeatedly within the 30-second cache window resolves from the cache
+   * without a network round-trip.
+   *
+   * **Side effects** (of a successful purchase that triggers `onUpdate`)
+   * Documented here because the consumer's `onUpdate` handler will observe
+   * the resulting state changes on the next refreshed array:
+   * - Points / gems / diamonds balance deducted per `purchase_type`. The
+   *   new balance becomes visible on the user's gamification profile via
+   *   the SDK's user-properties update channel (`ach_points_balance` /
+   *   `ach_gems_balance` / `ach_diamonds_balance`).
+   * - `pool` decremented for limited-stock items.
+   * - `type = 'bonus'` → a CRM bonus is granted; surfaces via
+   *   {@link getBonuses}.
+   * - `type = 'raffleticket'` → raffle tickets granted; surfaces via
+   *   `getRaffles`.
+   * - `type = 'changelevel'` → user's level adjusted; surfaces via
+   *   {@link getCurrentLevel}.
+   * - `type = 'minigamespin'` → SAW spin attempts granted; visible via the
+   *   mini-game APIs.
+   * - `type = 'prizedrop'` → one prize-drop attempt granted.
+   * - `type = 'tangible'` → no automatic gameplay effect; the purchase is
+   *   recorded for the operator's manual fulfillment (e.g. physical merch).
+   *
+   * **UI guidance**: see [UI Guide — `getStoreItems`](../../docs/ui/store/UIGuide_getStoreItems.md).
+   *
+   * @param params              Optional. Omit to fetch without subscribing.
+   * @param params.onUpdate     Callback invoked with the full refreshed
+   *                            catalog after every {@link buyStoreItem}
+   *                            round-trip on this connection. Each call to
+   *                            `getStoreItems` overwrites the prior
+   *                            callback. Never fires in visitor mode.
+   * @returns                   Promise resolving to the catalog of store
+   *                            items visible to the user. Empty array if
+   *                            the user has no items (or if the visitor
+   *                            proxy user has none configured).
+   *
+   * @example
+   * ```ts
+   * // 1. Initial fetch + subscribe to live updates
+   * const items = await window._smartico.api.getStoreItems({
+   *   onUpdate: (refreshed) => {
+   *     console.log('[smartico] store catalog refreshed after a purchase — re-render the entire store UI from this array, do not merge with prior state:', refreshed);
+   *
+   *     // 2. onUpdate fires only after the current user's own purchase
+   *     //    round-trip. Pool counts and can_buy flags are now current
+   *     //    for this user.
+   *     const soldOut = refreshed.filter(i => i.pool === 0);
+   *     if (soldOut.length > 0) {
+   *       console.log('[smartico] these items are now sold out — render an "Out of stock" overlay on each:', soldOut.map(i => i.id));
+   *     }
+   *   },
    * });
-   * ```
    *
-   * **Example in the Visitor mode**:
+   * // 3. Live affordability per item. Compare each item's price against
+   * //    the user's balance for its purchase_type (read from
+   * //    getUserProfile(), kept live by the SDK's user-properties channel).
+   * const profile = window._smartico.api.getUserProfile();
+   * const balances = {
+   *   points: profile?.ach_points_balance ?? 0,
+   *   gems: profile?.ach_gems_balance ?? 0,
+   *   diamonds: profile?.ach_diamonds_balance ?? 0,
+   * };
+   *
+   * // 4. Filter out items that are custom-section-only for the main view.
+   * const mainViewItems = items.filter(i => !i.only_in_custom_section);
+   *
+   * // 5. Bucket each item's button state for rendering.
+   * for (const i of mainViewItems) {
+   *   const activePrice = i.discounted_price ?? i.price;
+   *   const canAfford = balances[i.purchase_type] >= activePrice;
+   *   if (i.pool === 0) {
+   *     console.log('[smartico] item', i.id, 'is sold out — render disabled Buy with "Out of stock" overlay');
+   *   } else if (i.can_buy === false) {
+   *     console.log('[smartico] item', i.id, 'is not eligible — render disabled Buy and surface cant_buy_message on the popup:', i.cant_buy_message);
+   *   } else if (!canAfford) {
+   *     console.log('[smartico] item', i.id, 'is unaffordable — render disabled Buy and show "short by" line on popup; deficit =', activePrice - balances[i.purchase_type], i.purchase_type);
+   *   } else {
+   *     console.log('[smartico] item', i.id, 'is buyable — render enabled Buy at price', activePrice, i.purchase_type);
+   *   }
+   * }
+   *
+   * // 6. Visitor-mode equivalent: onUpdate is accepted but never fires.
+   * //    Re-poll if you need fresh data; buyStoreItem is not supported.
+   * // const visitorItems = await window._smartico.vapi('EN').getStoreItems();
+   * // console.log('[smartico] visitor catalog is the brand proxy user\'s — per-user fields are not meaningful');
    * ```
-   * _smartico.vapi('EN').getStoreItems().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *  @param params
-   *  @param params.onUpdate - callback function that will be called when the store items are updated
    */
   async getStoreItems({
     onUpdate
@@ -2586,15 +3614,168 @@ class WSAPI {
     }
     return OCache.use(onUpdateContextKey.StoreItems, ECacheContext.WSAPI, () => this.api.storeGetItemsT(this.userExtId), CACHE_DATA_SEC);
   }
-  /** Buy the specific shop item by item_id. Returns the err_code in case of success or error.
-   * **Example**:
-   * ```
-   * _smartico.api.buyStoreItem(1).then((result) => {
-   *     console.log(result);
+  /**
+   * Purchase a specific store item on behalf of the current user. Spends
+   * the user's points / gems / diamonds (depending on the item's
+   * `purchase_type`) and triggers reward delivery (bonus issuance, mini-game
+   * spin grant, level change, prize-drop, raffle ticket, or tangible item).
+   *
+   * A successful response (`err_code === 0`) means the funds have already
+   * been debited and the reward has been queued / granted server-side. The
+   * user's balance change arrives over a separate push channel, not in this
+   * response — see "Refresh after success" below.
+   *
+   * @remarks
+   * **Preconditions**
+   * Read the candidate item from `getStoreItems()` first and gate the call
+   * on these fields:
+   * - `can_buy === true` — server-derived; combines segment / visibility
+   *   conditions and any operator-set restrictions.
+   * - `pool == null || pool > 0` — `null` means unlimited stock; a positive
+   *   number means N units remain.
+   * - User's balance for the item's `purchase_type`
+   *   (`'points'` / `'gems'` / `'diamonds'`) is `>= price` (or
+   *   `>= discounted_price` if set). Balances are not on `TStoreItem` —
+   *   read them from the user properties returned by `getUserState()`.
+   * - If `active_till_date` is set, it is in the future.
+   *
+   * Calling without satisfying these will most likely return a non-zero
+   * `err_code` (one of the codes below). The SDK does not pre-validate
+   * — it forwards the request to the server unconditionally.
+   *
+   * **Error codes** (in `err_code`)
+   * - `0` — success; funds debited and reward delivered.
+   * - `1` — generic server error / control-group rejection. Treat as a
+   *   transient failure; show a "try again later" message.
+   * - `106` — label mismatch detected before the purchase transaction
+   *   (e.g. cross-label item id). From a consumer perspective: the item is
+   *   not purchasable by this user.
+   * - `11000` (`SHOP_NO_BALANCE`) — insufficient **points** balance.
+   *   Show an insufficient-balance message that names how many points are
+   *   missing (`price - current_points_balance`). The Buy button on the
+   *   item should already be disabled when this is the case; this code
+   *   normally fires only on a stale local balance.
+   * - `11001` (`SHOP_WRONG_LABEL`) — user-vs-item label mismatch detected
+   *   inside the purchase transaction. Distinct from `106`; both mean
+   *   "not purchasable by this user" from the consumer's perspective.
+   *   Surface as a generic "item not available" message.
+   * - `11002` (`SHOP_FAILED_TO_BUY_BONUS`) — the bonus configured on the
+   *   store item couldn't be issued (bad / disabled bonus config on the
+   *   operator side). Funds are NOT debited. Surface a generic error and
+   *   advise the user to contact support if it persists.
+   * - `11003` (`SHOP_FAILED_TO_BUY_SHOP_ITEM_CONDITION`) — the item's
+   *   **visibility** segment condition is not satisfied. Shouldn't be
+   *   reachable through a correctly-rendered UI (the item shouldn't be
+   *   shown in the first place); usually indicates a stale local store
+   *   list. Re-fetch via `getStoreItems()`.
+   * - `11004` (`SHOP_FAILED_TO_BUY_SHOP_ITEM_CONDITION_PURSHASE`) — the
+   *   item's **purchase** segment condition is not satisfied (the item is
+   *   visible but the user is not in the buyable segment). Surface a
+   *   localized "try again later" / "you're not eligible" message; do not
+   *   retry automatically.
+   * - `11005` (`SHOP_FAILED_TO_BUY_MATCHING_BONUS`) — matching-bonus
+   *   coupon issuance failed (variant of `11002` for matching-deposit
+   *   bonuses). Funds are NOT debited. Surface a generic error.
+   * - `11006` (`SHOP_FAILED_MAX_BOUGHT_ITEMS_REACHED`) — per-user purchase
+   *   cap reached (e.g. "max 1 per day"). Surface the item's
+   *   `limit_message` if set, otherwise `err_message`. Do not retry.
+   * - `11007` — bonus was issued but a follow-up redemption step failed
+   *   server-side. Funds **are** debited and the purchase event is recorded;
+   *   the consumer's UI should refresh the store list (auto-refresh will
+   *   fire) and surface a soft warning rather than a hard error.
+   * - `11009` (`SHOP_FAILED_POOL_EMPTY`) — stock pool is empty / sold out.
+   *   Show a "sold out" message; auto-refresh will mark the item as such
+   *   in subsequent `getStoreItems()` updates.
+   * - `11011` (`SHOP_NO_BALANCE_GEMS`) — insufficient **gems** balance.
+   *   Same handling as `11000` but for the gems currency.
+   * - `11012` (`SHOP_NO_BALANCE_DIAMONDS`) — insufficient **diamonds**
+   *   balance. Same handling as `11000` but for the diamonds currency.
+   * - `11014` (`SHOP_FAILED_PURCHASE_LIMITATION`) — outside the configured
+   *   purchase window (purchase weekday / time-of-day / window). Surface
+   *   the item's `purchase_limit_message` if set, otherwise `err_message`.
+   * - `9999` — uncaught server exception. Treat as a transient failure;
+   *   surface a generic error and allow retry.
+   * - other non-zero — generic server error. Surface `err_message` if any.
+   *
+   * **Idempotency**: NOT idempotent. The server performs no de-duplication —
+   * a second successful call deducts funds again and grants the reward
+   * again (subject to per-user purchase caps). The SDK itself does **not**
+   * enforce a single in-flight call. The consumer MUST guard the call site
+   * against double-clicks (set a local "buying" flag on click, clear it on
+   * response).
+   *
+   * **Refresh after success (and after failure)**
+   * The SDK automatically re-fetches the store item list and the
+   * purchased-items history on every response (success or error). Any
+   * `onUpdate` callback registered via `getStoreItems({ onUpdate })` (or
+   * the purchased-items equivalent) fires shortly after with the updated
+   * arrays — reflecting the new `pool`, `can_buy`, and any `purchased_*`
+   * flags. The user's balance (points / gems / diamonds) is exposed on the
+   * user-properties channel and updates independently; if the UI displays
+   * the balance, subscribe to user-property updates separately (it does
+   * NOT flow through `getStoreItems`).
+   *
+   * **Side effects** (consumer-observable on success)
+   * - User's points / gems / diamonds balance decreases by `price`
+   *   (or `discounted_price` if set).
+   * - Item's `pool` decrements by 1 (when `pool != null`).
+   * - Per-user purchase counters update — `purchased_today`,
+   *   `purchased_this_week`, `purchased_this_month` on the next
+   *   `getStoreItems()` refresh.
+   * - The reward is delivered: bonus issuance, mini-game spin grant,
+   *   level change, prize drop, raffle ticket, or tangible-item record.
+   *   Each reward type pushes its own follow-up update (e.g. a new
+   *   bonus appears in `getBonuses()`, the spin shows up in
+   *   `getMiniGames()`). Subscribe to each relevant channel separately.
+   * - A purchase row is appended to the user's purchase history,
+   *   surfaced via the purchased-items list.
+   *
+   * **UI guidance**: see [UI Guide — `buyStoreItem`](../../docs/ui/store/UIGuide_buyStoreItem.md).
+   *
+   * @param item_id  The store item `id` (from `getStoreItems()`).
+   * @returns `{ err_code, err_message }`; success when `err_code === 0`.
+   *
+   * @example
+   * ```ts
+   * const items = await window._smartico.api.getStoreItems({
+   *   onUpdate: (next) => console.log('[smartico] store items updated — re-render store grid with this fresh array', next),
    * });
+   * const item = items.find(i => i.id === itemId);
+   *
+   * if (!item) {
+   *   console.log('[smartico] item not in current store list — keep UI as-is, possibly refresh getStoreItems');
+   *   return;
+   * }
+   *
+   * // Local pre-checks: keep these aligned with the Buy-button decision matrix above.
+   * const effectivePrice = item.discounted_price ?? item.price;
+   * const inStock = item.pool == null || item.pool > 0;
+   * const inWindow = !item.active_till_date || Date.now() < item.active_till_date;
+   * if (!item.can_buy || !inStock || !inWindow) {
+   *   console.log('[smartico] buy not applicable — show disabled state with operator copy if any:', item.cant_buy_message);
+   *   return;
+   * }
+   *
+   * console.log('[smartico] buy starting — set in-flight flag, show loading dots on Buy button, keep detail modal open');
+   * const r = await window._smartico.api.buyStoreItem(item.id);
+   * console.log('[smartico] buy response received — clear in-flight flag');
+   *
+   * if (r.err_code === 0) {
+   *   console.log('[smartico] purchase successful — close the detail modal, show a success toast; getStoreItems onUpdate above will fire with the refreshed list (do NOT manually re-fetch)');
+   * } else if (r.err_code === 11000 || r.err_code === 11011 || r.err_code === 11012) {
+   *   console.error('[smartico] insufficient balance for this purchase_type — show insufficient-balance UI and how many units are missing:', item.purchase_type, effectivePrice);
+   * } else if (r.err_code === 11009) {
+   *   console.error('[smartico] item sold out — show a dedicated "Sold out" message; the auto-refresh will mark the card as such shortly');
+   * } else if (r.err_code === 11006) {
+   *   console.error('[smartico] per-user purchase cap reached — surface the operator-defined limit message:', item.limit_message || r.err_message);
+   * } else if (r.err_code === 11014) {
+   *   console.error('[smartico] outside purchase window — surface the operator-defined purchase-limit message:', item.purchase_limit_message || r.err_message);
+   * } else if (r.err_code === 11004 || r.err_code === 11003) {
+   *   console.error('[smartico] user not eligible / stale visibility — show a localized "try again later" message and let auto-refresh reconcile');
+   * } else {
+   *   console.error('[smartico] buy failed — show a generic error toast/modal with this message:', r.err_message);
+   * }
    * ```
-   *
-   * **Visitor mode: not supported**
    */
   async buyStoreItem(item_id) {
     const r = await this.api.buyStoreItem(this.userExtId, item_id);
@@ -2605,586 +3786,1796 @@ class WSAPI {
     return o;
   }
   /**
-   *
-   * Returns store categories
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.getStoreCategories().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getStoreCategories().then((result) => {
-   *      console.log(result);
-   * });
+   * Returns the list of active store categories configured for the current label.
+   * Categories are operator-defined groupings used to organize store items into tabs,
+   * sections, or filter chips in the gamification store UI.
+   *
+   * @remarks
+   * **What categories are**
+   * - Operator-defined groupings, configured per-label by the brand operator.
+   *   Only active categories are returned; inactive / archived / deleted ones are
+   *   filtered out server-side.
+   * - Each `TStoreCategory` exposes `{ id, name, order }`. `name` is the display label;
+   *   `order` is the relative position (lower = appears first).
+   * - The same set of categories is returned to every user of the label — there is no
+   *   per-segment / per-currency / per-device filtering on the category list. Item-level
+   *   segment visibility happens on {@link getStoreItems}, not here.
+   *
+   * **Localization / translation**
+   * - `name` is **pre-translated server-side** to the authenticated user's stored language.
+   *   In visitor mode, the language passed to `_smartico.vapi(lang)` drives the translation.
+   *   Consumers never need to translate `name` themselves.
+   * - Fallback if no translation exists for the user's language: the operator-set default
+   *   (typically the brand's English) value is returned. The field is never null for an
+   *   active category.
+   *
+   * **Sort order**
+   * The server does NOT pre-sort. Sort client-side before rendering:
+   * `categories.sort((a, b) => a.order - b.order)`.
+   *
+   * **How store items join to categories**
+   * Each `TStoreItem` exposes `category_ids: number[]` (zero-or-more, many-to-many).
+   * A single store item can belong to multiple categories, or to none. To render a
+   * "category → items" view:
+   * `items.filter(i => i.category_ids.includes(cat.id))`.
+   *
+   * **Uncategorized items**
+   * Items with `category_ids: []` are NOT represented by a synthetic "Other" entry
+   * in the response. The convention used by the reference store UI is to synthesize
+   * a client-side bucket (e.g. labelled "General") for items that have no category, OR
+   * for items whose `category_ids` reference a category that is no longer returned by
+   * this method (e.g. archived since the item was tagged). If you choose to render
+   * such a synthetic bucket, place it first (the reference UI uses an `order: -1`
+   * convention so it precedes all operator-defined categories).
+   *
+   * **Empty categories**
+   * A category may be returned even if zero items currently reference it (since this
+   * method does not join against items). The reference store UI hides such empty
+   * categories from its tab strip — replicate that filter if you don't want to render
+   * tabs that lead to empty content panels.
+   *
+   * **Refresh cadence / cache**
+   * - The SDK caches the response for 30 seconds. Subsequent calls within that window
+   *   return the cached array without a network round-trip.
+   * - The cache is NOT invalidated by store-item push events or purchases — operator-driven
+   *   category changes propagate at the next 30 s cache miss.
+   * - Cache is fully cleared on login / logout.
+   * - In **visitor mode**, additional server-side caching applies on top of the SDK cache;
+   *   worst-case staleness for an edited/added category is on the order of a few minutes
+   *   for anonymous viewers.
+   *
+   * **Idempotency**: safe. Read-only metadata fetch. Cache de-duplicates concurrent calls.
+   *
+   * **Side effects**: none — pure metadata read.
+   *
+   * **UI guidance**: see [UI Guide — `getStoreCategories`](../../docs/ui/store/UIGuide_getStoreCategories.md).
+   *
+   * @returns Array of `{ id, name, order }`. Empty array if no active categories are
+   *   configured for the label. `name` is pre-translated. Order is NOT applied — caller
+   *   must sort.
+   *
+   * @example
+   * ```ts
+   * const [categories, items] = await Promise.all([
+   *   window._smartico.api.getStoreCategories(),
+   *   window._smartico.api.getStoreItems(),
+   * ]);
+   *
+   * if (categories.length === 0) {
+   *   console.log('[smartico] no store categories configured — render items as a flat grid without tabs:', items.length);
+   * } else {
+   *   // Sort categories; build per-category item buckets; hide empty categories
+   *   const sorted = [...categories].sort((a, b) => a.order - b.order);
+   *   const tabs = sorted
+   *     .map(cat => ({ cat, items: items.filter(i => i.category_ids?.includes(cat.id)) }))
+   *     .filter(t => t.items.length > 0);
+   *
+   *   // Optional: synthesize an "Other" bucket for items with no (or unknown) category
+   *   const knownIds = new Set(categories.map(c => c.id));
+   *   const orphans = items.filter(i => !i.category_ids?.length || !i.category_ids.some(id => knownIds.has(id)));
+   *   if (orphans.length > 0) {
+   *     console.log('[smartico] uncategorized store items — render a client-synthesized "Other" tab at the front of the tab strip:', orphans.length);
+   *   }
+   *
+   *   console.log('[smartico] render store tabs in this order with these counts:', tabs.map(t => `${t.cat.name} (${t.items.length})`));
+   * }
+   *
+   * // Visitor mode — same shape, language driven by vapi(lang) argument
+   * const visitorCats = await window._smartico.vapi('DE').getStoreCategories();
+   * console.log('[smartico] visitor-mode store categories (names translated to DE):', visitorCats);
    * ```
    */
   async getStoreCategories() {
     return OCache.use(onUpdateContextKey.StoreCategories, ECacheContext.WSAPI, () => this.api.storeGetCategoriesT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Returns purchased items based on the provided parameters. "Limit" and "offset" indicate the range of items to be fetched.
-   * The maximum number of items per request is limited to 20.
-   * You can leave this params empty and by default it will return list of purchased items ranging from 0 to 20.
-   * The returned store items are cached for 30 seconds. But you can pass the onUpdate callback as a parameter.
-   * Note that each time you call getStorePurchasedItems with a new onUpdate callback, the old one will be overwritten by the new one.
-   * The onUpdate callback will be called on purchase of the store item and the last 20 items will be passed to it.
-   *
-   * **Example**:
+   * Fetches the authenticated user's **store purchase history** — a paginated,
+   * newest-first list of past store purchases (one row per redemption).
+   *
+   * Designed for a "My Purchases" / "Order History" screen. Each entry carries
+   * the same descriptive fields as the catalog card plus three history-only
+   * fields: `purchase_ts` (when the purchase happened), `purchase_points_amount`
+   * (the amount actually paid at that time — a price snapshot, not the
+   * current `price`), and `purchase_type` (`'points' | 'gems' | 'diamonds'`).
+   *
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode is not supported (the SDK only
+   *   exposes this method on the authenticated `_smartico.api`, not on
+   *   `_smartico.vapi`).
+   * - No prerequisite calls — calling without first fetching
+   *   {@link getStoreItems} or {@link getStoreCategories} is fine.
+   *
+   * **Pagination semantics**
+   * - **Offset-based**, newest-first. The server orders rows by purchase
+   *   timestamp **descending** and the SDK does NOT re-sort — items arrive
+   *   ready to render in display order.
+   * - `limit` — page size. **The SDK default is 20.** There is no server-side
+   *   hard cap, but 20 matches what the default Smartico UI uses end-to-end; the
+   *   protocol and storage layers were sized for this page size. Treat `20`
+   *   as the conventional/recommended value; passing a much larger limit will
+   *   return more rows but is not the supported integration pattern.
+   *   Avoid `limit <= 0` — the server peeks `limit + 1` rows internally, so
+   *   `limit = 0` returns 1 row with a misleading "has more" signal, and
+   *   negative values produce undefined results.
+   * - `offset` — number of items to skip from the start. The SDK default is
+   *   `0` (first page). For load-more pagination, pass
+   *   `offset = (previously-loaded items).length` on each subsequent call.
+   * - **No `hasMore` on the returned array.** `TStoreItem[]` is a flat list;
+   *   the underlying protocol response carries `hasMore` but it is not
+   *   surfaced through this method. Two ways for consumers to know they
+   *   reached the end:
+   *     1. The returned array is shorter than `limit` (definitive end), or
+   *     2. A subsequent call at `offset = previous.length` returns `[]`.
+   *   Either is reliable.
+   * - No date-range / category / status filter parameters — pagination is the
+   *   only server-side slicing. Apply any further filtering client-side.
+   *
+   * **No per-item fulfillment status**
+   * - History entries do NOT carry a `delivered` / `pending` / `cancelled` /
+   *   `refunded` field. The list contains rows for committed purchase
+   *   attempts; the server query does not filter by transaction-status, so in
+   *   practice the rows that appear are completed purchases (failed
+   *   transactions roll back and don't write a row). Treat every item as a
+   *   completed transaction unless a future SDK release adds an explicit
+   *   status field.
+   *
+   * **Bonus-type entries**
+   * - When the user redeemed a bonus item, the entry's `type` field surfaces
+   *   as `'bonus'`. **Known limitation:** the SDK transform currently maps
+   *   both `Bonus` and `Tangible` server-side item types to the same string
+   *   `'bonus'` — so the `type` field on history rows cannot distinguish a
+   *   bonus redemption from a tangible-prize redemption. The actual bonus
+   *   payload (wallet credit, free spins, etc.) is dispatched by the server
+   *   asynchronously and is NOT embedded in the history entry — consumers
+   *   that need bonus details should subscribe to bonus push events
+   *   separately rather than reading them from this list.
+   * - History rows render identically across types — there is no deep-link to
+   *   the bonus wallet or re-claim affordance on the row itself.
+   *
+   * **Per-row data**
+   * Each row uses the `TStoreItem` shape but populates four history-only
+   * fields not present on `getStoreItems` output. `purchase_ts` is the
+   * Unix-ms timestamp of the purchase — format with
+   * `new Date(purchase_ts).toLocaleString()` in the user's local timezone;
+   * no relative labels ("Today" / "Yesterday") are produced by the SDK.
+   * `purchase_points_amount` is the amount actually paid at the time of
+   * purchase — a snapshot of the historical price, which may differ from
+   * the item's current `price`. `purchase_type` is the currency actually
+   * charged (`'points' | 'gems' | 'diamonds'`); render the matching
+   * balance icon next to the amount. The convenience booleans
+   * `purchased_today` / `purchased_this_week` / `purchased_this_month` are
+   * computed client-side from the consumer's local clock — useful for
+   * grouping rows under "Today" / "This Week" headers.
+   *
+   * **Catalog fields on a history row**
+   * The promotional fields (`ribbon`, `discounted_price`,
+   * `discount_price_ribbon`, `custom_ribbon_image`, `active_till_date`)
+   * reflect the CURRENT catalog state of the item, NOT its state at
+   * purchase time — the default Smartico UI hides them on history rows to
+   * avoid implying that the historical purchase carried the current
+   * promotional banner. Descriptive marketing fields (`description`,
+   * `hint_text`, `related_games`) are typically suppressed on a compact
+   * history row. The current-purchasability fields `can_buy` and `pool`
+   * reflect now, not then — useful only if you render a "Buy Again"
+   * affordance on the row. One implementation gotcha: unlike
+   * `getStoreItems`, this method's transform does NOT auto-parse JSON
+   * strings in `custom_data` — call `JSON.parse()` yourself if you store
+   * JSON there.
+   *
+   * **Cache & refresh**
+   * - The SDK caches each `(limit, offset)` page separately for 30 seconds.
+   *   Repeated calls within that window resolve from cache without a
+   *   network round-trip.
+   * - The cache is invalidated and `onUpdate` (when registered) is invoked
+   *   automatically after a successful {@link buyStoreItem} call — the SDK
+   *   re-fetches the same page parameters that were registered together with
+   *   the current `onUpdate` callback and pushes the fresh array.
+   * - Multi-tab caveat: if the user has the same brand open in multiple
+   *   tabs, **all open tabs** receive the `onUpdate` event on a purchase,
+   *   not only the tab that initiated the buy. The event is scoped to the
+   *   current authenticated user — a different user's purchase never fires
+   *   this callback.
+   * - Only ONE `onUpdate` callback can be registered at a time. Each call to
+   *   `getStorePurchasedItems({ onUpdate })` overwrites the previous handler.
+   *
+   * **Idempotency**: safe. Pure read.
+   *
+   * **Side effects**: none — read-only.
+   *
+   * **UI guidance**: see [UI Guide — `getStorePurchasedItems`](../../docs/ui/store/UIGuide_getStorePurchasedItems.md).
+   *
+   * @param params - Optional pagination + callback bag.
+   * @param params.limit - Page size. Defaults to `20`. Use `20` as the
+   *   conventional value (matches the default Smartico UI end-to-end). Avoid
+   *   non-positive values.
+   * @param params.offset - Number of rows to skip from the newest end.
+   *   Defaults to `0`. For load-more pagination pass the current array
+   *   length.
+   * @param params.onUpdate - Optional callback invoked after a successful
+   *   {@link buyStoreItem} elsewhere in the session. Receives the refreshed
+   *   page for the same `(limit, offset)` used on the call that registered
+   *   this callback. Only ONE callback can be registered; each new call
+   *   overwrites the previous one. Pass a stable handler or
+   *   re-register intentionally on screen entry.
+   *
+   * @returns Promise resolving to an array of `TStoreItem` history entries
+   *   in newest-first order. Empty array if the user has no purchases (or
+   *   the requested `offset` is beyond the end). Each entry carries
+   *   `purchase_ts`, `purchase_points_amount`, `purchase_type`, and the
+   *   `purchased_today/this_week/this_month` convenience flags in addition
+   *   to the standard item fields.
+   *
+   * @example
+   * ```ts
+   * // Initial load + subscribe to refresh-on-purchase.
+   * const handleHistoryUpdate = (items: TStoreItem[]) => {
+   *   console.log(
+   *     '[smartico] purchase history refreshed — re-render the history list with these',
+   *     items.length,
+   *     'items (newest first):',
+   *     items,
+   *   );
+   * };
+   *
+   * try {
+   *   const firstPage = await _smartico.api.getStorePurchasedItems({
+   *     limit: 20,
+   *     offset: 0,
+   *     onUpdate: handleHistoryUpdate,
+   *   });
+   *
+   *   if (firstPage.length === 0) {
+   *     console.log('[smartico] no purchase history — render the empty state ("No purchases yet")');
+   *   } else {
+   *     console.log(
+   *       '[smartico] render',
+   *       firstPage.length,
+   *       'history rows (newest first). Show "Load more" button if length === 20:',
+   *       firstPage,
+   *     );
+   *
+   *     // Inspect the first entry's history-only fields.
+   *     const first = firstPage[0];
+   *     console.log(
+   *       '[smartico] most-recent purchase: name=', first.name,
+   *       'paid', first.purchase_points_amount, first.purchase_type,
+   *       'at', new Date(first.purchase_ts ?? 0).toLocaleString(),
+   *       '— format with toLocaleString (user-local time) on the row.',
+   *     );
+   *   }
+   *
+   *   // Load-more pattern: fetch page 2 once the user scrolls / clicks "Load more".
+   *   if (firstPage.length === 20) {
+   *     const nextPage = await _smartico.api.getStorePurchasedItems({
+   *       limit: 20,
+   *       offset: firstPage.length,
+   *     });
+   *     const isLastPage = nextPage.length < 20;
+   *     console.log(
+   *       '[smartico] appended page 2 —',
+   *       nextPage.length,
+   *       'rows.',
+   *       isLastPage ? 'Hide "Load more" — end reached.' : 'Keep "Load more" visible.',
+   *     );
+   *   }
+   * } catch (e) {
+   *   console.error(
+   *     '[smartico] failed to load purchase history — show a generic error placeholder or retry with backoff:',
+   *     e,
+   *   );
+   * }
    * ```
-   * _smartico.api.getStorePurchasedItems().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *
-   * **Visitor mode: not supported**
    */
   async getStorePurchasedItems({
     limit,
     offset,
     onUpdate
   } = {}) {
+    const requestLimit = limit === undefined ? 20 : limit;
+    const requestOffset = offset === undefined ? 0 : offset;
+    const cacheKey = this.storeHistoryCacheKey(requestLimit, requestOffset);
     if (onUpdate) {
       this.onUpdateCallback.set(onUpdateContextKey.StoreHistory, onUpdate);
+      this.storeHistoryOnUpdateParams = {
+        limit: requestLimit,
+        offset: requestOffset
+      };
+    }
+    return OCache.use(cacheKey, ECacheContext.WSAPI, () => this.api.storeGetPurchasedItemsT(this.userExtId, requestLimit, requestOffset), CACHE_DATA_SEC);
+  }
+  async updateStorePurchasedItems() {
+    const payload = await this.api.storeGetPurchasedItemsT(this.userExtId, this.storeHistoryOnUpdateParams.limit, this.storeHistoryOnUpdateParams.offset);
+    const cacheKey = this.storeHistoryCacheKey(this.storeHistoryOnUpdateParams.limit, this.storeHistoryOnUpdateParams.offset);
+    OCache.set(cacheKey, payload, ECacheContext.WSAPI);
+    const onUpdate = this.onUpdateCallback.get(onUpdateContextKey.StoreHistory);
+    if (onUpdate) {
+      onUpdate(payload);
     }
-    return OCache.use(onUpdateContextKey.StoreHistory, ECacheContext.WSAPI, () => this.api.storeGetPurchasedItemsT(this.userExtId, limit, offset), CACHE_DATA_SEC);
   }
+  async updateStoreItems() {
+    const payload = await this.api.storeGetItemsT(this.userExtId);
+    this.updateEntity(onUpdateContextKey.StoreItems, payload);
+  }
+}
+
+/** @group Tournaments */
+class WSAPITournaments extends WSAPIStore {
   /**
-   * Returns missions & badges categories
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.getAchCategories().then((result) => {
-   *      console.log(result);
+   * Returns the list of tournaments currently visible to the user, scoped
+   * server-side to what the user's segments qualify them to see. Optionally
+   * subscribes to live updates via `onUpdate`: the callback is invoked with
+   * the full refreshed list whenever the user registers in a tournament.
+   *
+   * The returned list is the canonical source of truth for tournament
+   * lobby state (`is_user_registered`, `registration_status`,
+   * `is_in_progress`, `is_can_register`, etc.). Consumers should NOT
+   * mutate it optimistically — always wait for the `onUpdate` callback
+   * (or a fresh fetch after the 30 s cache window) to observe new state.
+   *
+   * @remarks
+   * **Subscription model (`onUpdate`)**
+   * The callback receives the FULL refreshed list (never a diff/patch).
+   * Each subsequent call to `getTournamentsList({ onUpdate })` REPLACES
+   * the prior callback — only one active subscriber at a time. Pass
+   * `onUpdate: undefined` (or omit it) to keep the prior callback in
+   * place; the callback is never auto-cleared.
+   *
+   * **Update triggers** — the callback fires when:
+   *
+   * 1. `registerInTournament(...)` resolves on this connection (any
+   *    `err_code`). The refreshed list reflects the new
+   *    `is_user_registered` / `registration_status` /
+   *    `registration_count` on the affected tournament.
+   *
+   * Does NOT fire for: tournament lifecycle transitions (start, finish,
+   * cancellation), score updates, other users' registrations, or
+   * operator-side BO edits. Those changes surface only on the next
+   * cache miss (after the 30 s TTL) — poll manually if your UI needs
+   * sub-30s lifecycle freshness.
+   *
+   * **Server-side filtering** (what's excluded before the SDK sees it)
+   * The server filters by visibility segment and entry segment, removes
+   * tournaments past their post-finish display window, and excludes
+   * tournaments not yet published. SDK consumers receive only items
+   * the user is eligible to see; no client-side gating is required.
+   *
+   * **Reading state from the returned item**
+   * Drive list bucketing and CTA labels from the SDK-computed booleans
+   * (`is_active`, `is_can_register`, `is_cancelled`, `is_finished`,
+   * `is_in_progress`, `is_upcoming`), NOT from raw `start_time` /
+   * `end_time` comparisons — the booleans encode the canonical
+   * lifecycle states and already reflect server-side rules around
+   * qualifying scores and late registration. `is_user_registered` is
+   * independent of `is_can_register` — a registered user has
+   * `is_user_registered: true` and `is_can_register: false`. The `me`
+   * block (if present) carries the user's own leaderboard position and
+   * score; it's undefined for unregistered users, users without any
+   * recorded score, and visitor-mode sessions. The `prize_pool_short`
+   * field carries the operator-supplied summary string ("$10,000",
+   * "Mixed prizes") for compact card rendering; the full per-place
+   * `prizes[]` breakdown is also populated here but is typically
+   * rendered only in the detail view via
+   * {@link getTournamentInstanceInfo}.
+   *
+   * **Cross-references**
+   * Tournaments with `is_clan_based: true` group participants by clan —
+   * see {@link getClanTournamentPlayers} for fetching the players list
+   * of a specific clan within a clan tournament. The detailed lobby
+   * view (with full player leaderboard and prize structure) comes from
+   * {@link getTournamentInstanceInfo}. Tournaments with
+   * `custom_section_id` belong to an operator-defined custom section
+   * (resolve metadata via `getCustomSections()`).
+   *
+   * **Cache TTL**: the SDK caches the response for 30 seconds. Cache is
+   * fully cleared on login / logout.
+   *
+   * **Idempotency**: safe. Read-only. Repeated calls within the cache
+   * window return a deep-cloned cached array without a network
+   * round-trip.
+   *
+   * **Side effects**: none — pure metadata read.
+   *
+   * **UI guidance**: see [UI Guide — `getTournamentsList`](../../docs/ui/tournaments/UIGuide_getTournamentsList.md).
+   *
+   * **Visitor mode**: supported. The same shape is returned, scoped to
+   * the brand's public tournament list. Per-user fields (`me`,
+   * `is_user_registered`, `registration_status`) are not meaningful.
+   * The `onUpdate` callback is accepted but never fires (registration
+   * mutations are not supported in visitor mode).
+   *
+   * @param params              Optional. Omit to fetch without subscribing.
+   * @param params.onUpdate     Callback invoked with the full refreshed
+   *                            tournament list after every
+   *                            {@link registerInTournament} round-trip on
+   *                            this connection. Each call overwrites the
+   *                            prior callback. Never fires in visitor mode.
+   * @returns                   Promise resolving to the array of
+   *                            tournaments visible to the user. Empty
+   *                            array if no tournaments are visible.
+   *
+   * @example
+   * ```ts
+   * const tournaments = await window._smartico.api.getTournamentsList({
+   *   onUpdate: (refreshed) => {
+   *     console.log('[smartico] tournament list refreshed — re-render the lobby UI from this array, do not merge with prior state:', refreshed);
+   *     const justRegistered = refreshed.filter(t => t.is_user_registered);
+   *     console.log('[smartico] user is now registered in these tournaments:', justRegistered.map(t => t.name));
+   *   },
    * });
-   * ```
    *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getAchCategories().then((result) => {
-   *      console.log(result);
-   * });
+   * // Bucket items by lifecycle state for a tabbed UI.
+   * const live = tournaments.filter(t => t.is_in_progress);
+   * const upcoming = tournaments
+   *   .filter(t => t.is_upcoming && !t.is_user_registered)
+   *   .sort((a, b) => a.start_time - b.start_time);
+   * const mine = tournaments.filter(t => t.is_user_registered);
+   * const finished = tournaments.filter(t => t.is_finished);
+   *
+   * console.log('[smartico] render lobby tabs with these counts: live=', live.length,
+   *   'upcoming=', upcoming.length, 'mine=', mine.length, 'finished=', finished.length);
+   *
+   * // Featured tournament: pin to position 0 of the Overview/Top tabs.
+   * const featured = tournaments.find(t => t.is_featured && !t.is_cancelled);
+   * if (featured) {
+   *   console.log('[smartico] featured tournament — pin to position 0 of the Overview tab:', featured.name);
+   * }
+   *
+   * // Visitor mode: onUpdate accepted but never fires; re-poll if needed.
+   * // const visitorList = await window._smartico.vapi('EN').getTournamentsList();
    * ```
-   *
-   * */
-  async getAchCategories() {
-    return OCache.use(onUpdateContextKey.AchCategories, ECacheContext.WSAPI, () => this.api.achGetCategoriesT(this.userExtId), CACHE_DATA_SEC);
+   */
+  async getTournamentsList({
+    onUpdate
+  } = {}) {
+    if (onUpdate) {
+      this.onUpdateCallback.set(onUpdateContextKey.TournamentList, onUpdate);
+    }
+    return OCache.use(onUpdateContextKey.TournamentList, ECacheContext.WSAPI, () => this.api.tournamentsGetLobbyT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Returns list of custom sections
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.getCustomSections().then((result) => {
-   *      console.log(result);
-   * });
+   * Returns the full detail of a single tournament instance — adds the
+   * player leaderboard, the full prize structure, and (for clan
+   * tournaments) the clan leaderboard and per-clan prize structure on
+   * top of everything already in `TTournament`. Use this to power a
+   * tournament detail / lobby screen after the user picks an item from
+   * {@link getTournamentsList}.
+   *
+   * Live leaderboard updates require manual re-fetching — there is no
+   * subscription model, no push event, and no client-side cache (each
+   * call hits the server). The default Smartico UI polls every 3 seconds
+   * while the detail view is open.
+   *
+   * @remarks
+   * **Preconditions**
+   * Pass a valid `tournamentInstanceId` read from `TTournament.instance_id`
+   * on an item returned by {@link getTournamentsList}. The method works
+   * standalone — calling `getTournamentsList()` first is not required by
+   * the SDK, but is the only stable source of valid IDs.
+   *
+   * **Refresh model**
+   * - **No subscription.** This is a one-shot promise; call again to
+   *   refresh.
+   * - **No client cache.** Every call sends a network request and
+   *   returns the latest server snapshot. Safe to poll on an interval —
+   *   the default Smartico UI uses 3 s while the detail view is visible.
+   * - **No push event** invalidates or refreshes detail state. Score
+   *   changes, registration count changes, lifecycle transitions — all
+   *   require a fresh `getTournamentInstanceInfo` call.
+   *
+   * **Returned shape — beyond `TTournament`**
+   * `TTournamentDetailed` extends `TTournament` with the following
+   * additional data: a `players[]` leaderboard sorted server-side by
+   * score (only members with at least one recorded score); the user's
+   * own `me` block carrying their rank and score (undefined when not
+   * registered or when the user has no score yet); a full per-place
+   * `prizes[]` array (place range, type, points / gems / diamonds
+   * amounts, image, name); and `related_games[]` if the operator has
+   * associated games with this tournament. For clan tournaments
+   * (`is_clan_based === true`), the response also carries
+   * `clan_leaderboard[]` (ranked clans with `total_score` and
+   * `contributing_members`), `clan_prize_structure[]` (per-clan-place
+   * prize tiers — Fixed vs Dynamic, with ScoreWeighted /
+   * EqualSplit distribution for Dynamic prizes), `user_clan_id` (the
+   * user's own clan), and the advisory `user_position_in_clan` /
+   * `user_score_in_clan` fields.
+   *
+   * **Idempotency**: safe. Read-only. Each call returns the latest
+   * server snapshot.
+   *
+   * **Side effects**: none — pure metadata read.
+   *
+   * **UI guidance**: see [UI Guide — `getTournamentInstanceInfo`](../../docs/ui/tournaments/UIGuide_getTournamentInstanceInfo.md).
+   *
+   * **Visitor mode**: not supported. Use {@link getTournamentsList} for
+   * the public lobby list in visitor mode; the detail endpoint requires
+   * an authenticated session.
+   *
+   * @param tournamentInstanceId  The `instance_id` from a `TTournament`
+   *                              returned by {@link getTournamentsList}.
+   * @returns                     Promise resolving to `TTournamentDetailed`.
+   *                              Rejects if the instance ID is invalid
+   *                              or the user lacks visibility for it.
+   *
+   * @example
+   * ```ts
+   * const tournaments = await window._smartico.api.getTournamentsList();
+   * const tournament = tournaments[0];
+   *
+   * console.log('[smartico] loading detail view for tournament', tournament.instance_id);
+   * const detail = await window._smartico.api.getTournamentInstanceInfo(tournament.instance_id);
+   *
+   * console.log('[smartico] render detail with', detail.players?.length ?? 0,
+   *   'players,', detail.prizes?.length ?? 0, 'prize tiers');
+   *
+   * if (detail.is_clan_based && detail.clan_leaderboard) {
+   *   console.log('[smartico] clan tournament — render clan leaderboard tab with',
+   *     detail.clan_leaderboard.length, 'clans');
+   *   if (detail.user_clan_id != null) {
+   *     console.log('[smartico] user belongs to clan', detail.user_clan_id,
+   *       '— highlight that row in the clan leaderboard');
+   *   }
+   * }
+   *
+   * // Live leaderboard updates — poll every 3 seconds while the detail view is open.
+   * const pollId = setInterval(async () => {
+   *   try {
+   *     const fresh = await window._smartico.api.getTournamentInstanceInfo(tournament.instance_id);
+   *     console.log('[smartico] detail refreshed — re-render player + clan leaderboards from this new snapshot:', fresh);
+   *   } catch (e) {
+   *     console.error('[smartico] tournament detail poll failed — keep showing last snapshot, retry on next tick:', e);
+   *   }
+   * }, 3_000);
+   * // clearInterval(pollId) when the detail view closes.
+   *
+   * if (detail.me) {
+   *   console.log('[smartico] current user is rank', detail.me.position,
+   *     'with', detail.me.scores, 'points — render the sticky "me" panel below the leaderboard');
+   * }
    * ```
-   *
-   * **Example in the Visitor mode**:
+   */
+  async getTournamentInstanceInfo(tournamentInstanceId) {
+    return this.api.tournamentsGetInfoT(this.userExtId, tournamentInstanceId);
+  }
+  /**
+   * Returns the ranked players of a specific clan within a clan-based
+   * tournament instance. Used to drill down from the clan-leaderboard
+   * tab on the tournament detail view into a single clan's member
+   * roster.
+   *
+   * The server returns up to roughly 20 players (top-N by score
+   * descending). Server-side ordering is already by `scores` DESC
+   * (equivalent to `position` ASC) — no client-side re-sort is
+   * required.
+   *
+   * @remarks
+   * **Preconditions**
+   * Pass a valid `tournamentInstanceId` (read from `TTournament.instance_id`
+   * returned by {@link getTournamentsList}) and a `clanId` (read from
+   * `TTournamentDetailed.clan_leaderboard[].clan_id` returned by
+   * {@link getTournamentInstanceInfo}). The tournament should be
+   * clan-based (`is_clan_based === true`); calling this against a
+   * non-clan tournament typically returns an empty `players` array.
+   *
+   * **Refresh model**
+   * - **No subscription.** This is a one-shot promise.
+   * - **No client cache.** Every call hits the server.
+   * - **No push event** refreshes the response. Live updates to clan
+   *   member rankings require a fresh call.
+   * - The default Smartico UI fetches this once when the user opens the
+   *   clan-drill-down modal and does NOT refresh while the modal is
+   *   open. If your UI needs live updates, re-call on an interval; the
+   *   clan leaderboard at the parent level (via
+   *   {@link getTournamentInstanceInfo}) does refresh via its own
+   *   polling cadence.
+   *
+   * **Returned shape**
+   * `TClanTournamentPlayers` carries the requested clan's identity
+   * (`clan_id`, `clan_public_meta.name`, `clan_public_meta.image_url`)
+   * alongside the `players[]` array — each entry has `position`,
+   * `scores`, `public_username`, `clean_ext_user_id`, `avatar_id`,
+   * `avatar_real_id`, the resolved `avatar_url`, `user_id`, and the
+   * `is_me` flag identifying the current user's row. The `clan_id` and
+   * `clan_public_meta` on the response echo the input clan — the
+   * default Smartico UI ignores them and renders the header from the
+   * caller-side `ClanLeaderboardEntry` object, but they're available
+   * for consumers that don't already have that context.
+   *
+   * **Username display**: prefer `clean_ext_user_id` when set, falling
+   * back to `public_username`. The default Smartico UI uses
+   * `clean_ext_user_id || public_username || ''`.
+   *
+   * **Idempotency**: safe. Read-only. Each call returns the latest
+   * server snapshot.
+   *
+   * **Side effects**: none — pure metadata read.
+   *
+   * **UI guidance**: see [UI Guide — `getClanTournamentPlayers`](../../docs/ui/tournaments/UIGuide_getClanTournamentPlayers.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param tournamentInstanceId  The tournament `instance_id` from a
+   *                              clan-based `TTournament`.
+   * @param clanId                The clan ID from
+   *                              `TTournamentDetailed.clan_leaderboard[].clan_id`.
+   * @returns                     Promise resolving to
+   *                              `TClanTournamentPlayers`. An invalid
+   *                              ID combination typically yields an
+   *                              empty `players` array; the SDK does
+   *                              not distinguish "no scores yet" from
+   *                              "invalid IDs" — both manifest as an
+   *                              empty list.
+   *
+   * @example
+   * ```ts
+   * const detail = await window._smartico.api.getTournamentInstanceInfo(tournamentInstanceId);
+   * if (!detail.is_clan_based || !detail.clan_leaderboard) {
+   *   console.log('[smartico] not a clan tournament — skip clan drill-down');
+   *   return;
+   * }
+   *
+   * // User clicked a clan row in the leaderboard.
+   * const clickedClan = detail.clan_leaderboard[0];
+   *
+   * console.log('[smartico] opening clan drill-down — show modal skeleton while loading');
+   * const result = await window._smartico.api.getClanTournamentPlayers(
+   *   tournamentInstanceId,
+   *   clickedClan.clan_id,
+   * );
+   *
+   * if (result.players.length === 0) {
+   *   console.log('[smartico] clan has no ranked players yet — render empty state ("No leaders yet")');
+   * } else {
+   *   console.log('[smartico] render clan member rows with .is-me highlight on the current user;',
+   *     result.players.length, 'players ranked');
+   *   const me = result.players.find(p => p.is_me);
+   *   if (me) {
+   *     console.log('[smartico] current user rank in this clan:', me.position, 'score:', me.scores);
+   *   }
+   * }
    * ```
-   * _smartico.vapi('EN').getCustomSections().then((result) => {
-   *      console.log(result);
+   */
+  async getClanTournamentPlayers(tournamentInstanceId, clanId) {
+    return this.api.clanTournamentGetPlayers(this.userExtId, tournamentInstanceId, clanId);
+  }
+  /**
+   * Registers the authenticated user in the specified tournament instance.
+   * For tournaments with a buy-in cost, the user's balance is debited
+   * synchronously before the response is returned; for free tournaments
+   * the call is a simple membership add.
+   *
+   * A successful response (`err_code === 0`) means the registration row
+   * exists server-side, the buy-in (if any) has been deducted, and the
+   * SDK has already triggered a refresh of the tournament lobby cache.
+   *
+   * @remarks
+   * **Preconditions**
+   * Read the candidate from {@link getTournamentsList} and gate the call
+   * on `is_can_register === true`. This composite flag already encodes:
+   * not already registered, slot available
+   * (`registration_count < players_max_count`), tournament status is
+   * REGISTER (or STARTED with late-registration enabled), and the
+   * registration type is not AUTO. The SDK forwards the call
+   * unconditionally — calling without satisfying these will return one
+   * of the error codes below.
+   *
+   * For clan tournaments (`is_clan_based === true`), the user must
+   * already belong to a clan before calling. If they don't, prompt them
+   * to pick a clan first via {@link joinClan}, then call
+   * `registerInTournament` after the clan-join resolves. See "Error
+   * codes" `1010` below for the server-side safety net.
+   *
+   * **Error codes** (in `err_code`, typed as {@link TournamentRegistrationError})
+   * - `0` — success; the registration is persisted, buy-in deducted,
+   *   tournament lobby refresh fires.
+   * - `1010` — `TOURNAMENT_USER_CANNOT_JOIN_WITHOUT_CLAN`: clan-based
+   *   tournament and the user has no clan. Surface the clan-pick flow
+   *   (e.g. open a clan-pick modal driven by {@link getClans} +
+   *   {@link joinClan}), then retry registration.
+   * - `30001` — `TOURNAMENT_INSTANCE_NOT_FOUND`: instance ID is invalid
+   *   or the tournament was deleted. Refresh the lobby via
+   *   `getTournamentsList()` and hide the entry from the UI.
+   * - `30002` — `TOURNAMENT_REGISTRATION_NOT_ENOUGH_POINTS`: insufficient
+   *   points balance for a points-cost tournament. Show an
+   *   insufficient-balance UI naming the deficit.
+   * - `30003` — `TOURNAMENT_INSTANCE_NOT_IN_STATE`: tournament is no
+   *   longer in a registerable state (finished, cancelled, finalizing,
+   *   or not yet published with late registration disabled). Refresh
+   *   the lobby; the button should hide.
+   * - `30004` — `TOURNAMENT_ALREADY_REGISTERED`: user is already
+   *   registered. Treat as idempotent success — hide the Register button
+   *   and refresh the lobby. Usually indicates a stale local state
+   *   (e.g. registered from another tab).
+   * - `30005` — `TOURNAMENT_USER_DONT_MATCH_CONDITIONS`: user fails the
+   *   tournament's segment / entry conditions. Prefer
+   *   `tournament.segment_dont_match_message` (operator-supplied) over
+   *   `err_message` when both are available.
+   * - `30006` — `TOURNAMENT_USER_NOT_REGISTERED`: anomalous on a fresh
+   *   register call; usually indicates a server-side race. Treat as a
+   *   generic transient error.
+   * - `30007` — `TOURNAMENT_CANT_CHANGE_REGISTRATION_STATUS`: status
+   *   transition not allowed (e.g. re-registering after a finished /
+   *   cancelled tournament). Show a generic error; do not retry.
+   * - `30008` — `TOURNAMENT_MAX_REGISTRATIONS_REACHED`: the tournament
+   *   filled up between the lobby fetch and the registration click.
+   *   Refresh the lobby — the button will hide on the refreshed item.
+   * - `300010` — insufficient **gems** balance (gems-cost tournament).
+   *   Same UI handling as `30002` but for the gems currency.
+   * - `300011` — insufficient **diamonds** balance (diamonds-cost
+   *   tournament). Same as `300010` but for diamonds.
+   * - other non-zero — generic server error. Surface `err_message` if any.
+   *
+   * Note: clan-tournament registration can occasionally surface error
+   * codes from the clan-join domain (e.g. `1011` — joined-after-start)
+   * via the same response path. These are members of `JoinClanErrorCode`,
+   * not `TournamentRegistrationError`. Branch on the numeric value.
+   *
+   * **Idempotency**: NOT idempotent. A second call on the same instance
+   * returns `30004` once the first call has succeeded. The SDK does NOT
+   * enforce an in-flight lock. The consumer MUST guard the call site
+   * against double-clicks (set a local "registering" flag on click, clear
+   * it on response).
+   *
+   * **Refresh after success (and after failure)**
+   * The SDK automatically refreshes the tournament lobby cache on every
+   * response (success OR error) and fires any `onUpdate` callback
+   * registered via `getTournamentsList({ onUpdate })`. After
+   * `err_code === 0`, the affected item's `is_user_registered` /
+   * `registration_status` / `registration_count` reflect the new
+   * registered state on the refreshed array. Note that
+   * {@link getTournamentInstanceInfo} is NOT auto-refreshed — if the
+   * detail screen is open, call it again manually.
+   *
+   * The user's balance (points / gems / diamonds) is exposed on the
+   * user-properties channel and updates independently of this call's
+   * response — subscribe to user-property updates separately if your UI
+   * shows the balance.
+   *
+   * **Side effects** (consumer-observable on success)
+   * - Balance debited synchronously by the buy-in amount in the
+   *   tournament's currency (`registration_cost_points`,
+   *   `registration_cost_gems`, or `registration_cost_diamonds`). For
+   *   free tournaments no deduction occurs.
+   * - Server-side analytics events fire downstream
+   *   (`tournament_user_registered` for immediate-registration types;
+   *   `tournament_user_registration_pending` or
+   *   `tournament_registered_pending_qualification` for
+   *   manual-approval / qualification-based types).
+   * - Any operator-configured on-join prizes are distributed (e.g.
+   *   welcome bonus). These surface via the relevant follow-up channels
+   *   (e.g. {@link getBonuses}).
+   *
+   * **UI guidance**: see [UI Guide — `registerInTournament`](../../docs/ui/tournaments/UIGuide_registerInTournament.md).
+   *
+   * **Visitor mode**: not supported. Calling from a visitor session
+   * returns a generic error, not a typed `TournamentRegistrationError`.
+   *
+   * @param tournamentInstanceId  The `instance_id` from `TTournament`
+   *                              (NOT the template `tournament_id`).
+   * @returns `{ err_code, err_message }`; success when `err_code === 0`
+   *          (or `30004` when treated as idempotent no-op).
+   *
+   * @example
+   * ```ts
+   * const tournaments = await window._smartico.api.getTournamentsList({
+   *   onUpdate: (refreshed) => console.log('[smartico] tournament list updated — re-render lobby from this array', refreshed),
    * });
+   * const tournament = tournaments.find(t => t.instance_id === instanceId);
+   *
+   * if (!tournament) {
+   *   console.log('[smartico] tournament not in current lobby — refresh getTournamentsList and retry');
+   *   return;
+   * }
+   * if (!tournament.is_can_register) {
+   *   console.log('[smartico] tournament not currently registerable — keep CTA disabled');
+   *   return;
+   * }
+   *
+   * // Clan tournament + user has no clan → resolve clan first.
+   * if (tournament.is_clan_based) {
+   *   const userProfile = window._smartico.api.getUserProfile();
+   *   const userClanId = userProfile?.clan_id;
+   *   if (userClanId == null) {
+   *     console.log('[smartico] clan tournament — open the clan-pick modal first; after joinClan resolves, call registerInTournament again');
+   *     return;
+   *   }
+   * }
+   *
+   * console.log('[smartico] registration starting — set in-flight flag, show loading dots on the Join button, keep modal open');
+   * const r = await window._smartico.api.registerInTournament(tournament.instance_id);
+   * console.log('[smartico] registration response received — clear in-flight flag');
+   *
+   * if (r.err_code === 0 || r.err_code === 30004) {
+   *   console.log('[smartico] registered (or was already) — close any modal, show a success toast; getTournamentsList onUpdate above will fire with the refreshed array');
+   * } else if (r.err_code === 1010) {
+   *   console.log('[smartico] clan required — open the clan-pick modal again (this is the server-side safety net for a clan-leave race)');
+   * } else if (r.err_code === 30002) {
+   *   console.error('[smartico] insufficient points — show insufficient-balance UI; deficit:', tournament.registration_cost_points);
+   * } else if (r.err_code === 300010) {
+   *   console.error('[smartico] insufficient gems — show insufficient-balance UI; deficit:', tournament.registration_cost_gems);
+   * } else if (r.err_code === 300011) {
+   *   console.error('[smartico] insufficient diamonds — show insufficient-balance UI; deficit:', tournament.registration_cost_diamonds);
+   * } else if (r.err_code === 30005) {
+   *   console.error('[smartico] segment mismatch — prefer the operator-supplied message:', tournament.segment_dont_match_message || r.err_message);
+   * } else if (r.err_code === 30008) {
+   *   console.error('[smartico] tournament full — auto-refresh will hide the button on the refreshed lobby item');
+   * } else {
+   *   console.error('[smartico] registration failed — show a generic error toast with this message:', r.err_message);
+   * }
    * ```
-   *
-   * */
-  async getCustomSections() {
-    return OCache.use(onUpdateContextKey.CustomSections, ECacheContext.WSAPI, () => this.api.customSectionsGetT(this.userExtId), CACHE_DATA_SEC);
+   */
+  async registerInTournament(tournamentInstanceId) {
+    const r = await this.api.registerInTournament(this.userExtId, tournamentInstanceId);
+    const o = {
+      err_code: r.errCode,
+      err_message: r.errMsg
+    };
+    return o;
+  }
+  async updateTournaments() {
+    const payload = await this.api.tournamentsGetLobbyT(this.userExtId);
+    this.updateEntity(onUpdateContextKey.TournamentList, payload);
   }
+}
+
+/** @group Clans */
+class WSAPIClans extends WSAPITournaments {
   /**
-   * Returns the list of mini-games configured for the current user (not filtered by spin availability or Widget visibility).
-   * The returned list of mini-games is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call getMiniGames with a new onUpdate callback, the old one will be overwritten by the new one.
-   * The onUpdate callback will be called on available spin count change, if mini-game has increasing jackpot per spin or won prize is spin/jackpot and if max count of the available user spins equals one, also if the spins were issued to the user manually in the BO. Updated templates will be passed to onUpdate callback.
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.getMiniGames().then((result) => {
-   *      console.log(result);
+   * Returns the active clans visible to the current user along with the
+   * user's own membership state (`user_clan_id`, `cooldown_until`,
+   * `join_date`). Use this to power a clan-picker / clan-browser screen.
+   *
+   * The returned `clans[]` is server-sorted by `rating_position` ASC
+   * (1 = highest-ranked). The server has already filtered out archived
+   * clans, clans the user fails segment conditions for, and (when any
+   * clan has a non-zero score) clans with a zero rating score.
+   *
+   * @remarks
+   * **Subscription model (`onUpdate`)**
+   * The callback receives the FULL refreshed `TClans` payload (never a
+   * diff/patch). Each subsequent call to `getClans({ onUpdate })`
+   * REPLACES the prior callback. Pass `onUpdate: undefined` (or omit
+   * it) to keep the prior callback in place; the callback is never
+   * auto-cleared.
+   *
+   * **Update triggers** — note that, unlike most other subscription
+   * methods in the SDK, this callback is **poll-driven only**. There
+   * is NO server push that refreshes the clans list. The callback
+   * fires when:
+   *
+   * 1. The 30-second cache TTL expires and a subsequent `getClans()`
+   *    call (from the consumer) triggers a fresh fetch.
+   *
+   * Consequence: clan-membership changes (other users joining your
+   * clan, an operator-driven kick, a clan being archived) surface
+   * only on the next consumer-driven fetch. If your UI needs
+   * near-live state, poll `getClans()` on an interval; or re-call
+   * after a {@link joinClan} resolves to pick up the new
+   * `user_clan_id` immediately.
+   *
+   * **Reading state from the returned payload**
+   * Drive list rendering from `clans[]` (already sorted). Identify
+   * the user's own clan via `clan.clan_id === user_clan_id`
+   * (`null` for clanless users). Detect an active switch-cooldown
+   * with `cooldown_until !== null` — when set, the user cannot join
+   * any clan until the cooldown expires, even clans they could
+   * normally join. The cooldown is **user-level**, not per-clan.
+   *
+   * `cooldown_until` is an ISO 8601 UTC datetime string with no
+   * timezone suffix (`"YYYY-MM-DDTHH:MM:SS"`). Parse as UTC:
+   * `new Date(cooldown_until + 'Z')` or `moment.utc(cooldown_until)`.
+   * Display in the user's local time. The default cooldown period
+   * is configured per label by the operator (typically 7 days).
+   *
+   * `rating_position` is a global rank computed server-side across
+   * all active clans in the label (1 = highest-rated). Because some
+   * clans may be hidden by per-user segment visibility, positions
+   * the user sees may skip (e.g. 1, 3, 7) — don't assume the array
+   * spans a contiguous range.
+   *
+   * The `entry_fee_currency_type_id` enum on each clan uses values
+   * `0` = points, `1` = gems, `2` = diamonds, `3` = free. Compare
+   * `entry_fee_amount` against the user's matching balance (from
+   * {@link getUserProfile}) to drive Join button affordability.
+   *
+   * **Cache TTL**: the SDK caches the response for 30 seconds. Cache
+   * is fully cleared on login / logout.
+   *
+   * **Idempotency**: safe. Read-only. Repeated calls within the
+   * cache window return a deep-cloned cached payload without a
+   * network round-trip.
+   *
+   * **Side effects**: none — pure metadata read.
+   *
+   * **UI guidance**: see [UI Guide — `getClans`](../../docs/ui/clans/UIGuide_getClans.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param params              Optional. Omit to fetch without subscribing.
+   * @param params.onUpdate     Callback invoked with the full refreshed
+   *                            `TClans` payload whenever the 30 s cache
+   *                            expires and a subsequent fetch lands.
+   *                            Each call to `getClans` overwrites the
+   *                            prior callback.
+   * @returns                   Promise resolving to `TClans`. Empty
+   *                            `clans` array if no clans are visible.
+   *
+   * @example
+   * ```ts
+   * const result = await window._smartico.api.getClans({
+   *   onUpdate: (refreshed) => {
+   *     console.log('[smartico] clans payload refreshed (poll-driven; ~30 s cadence) — re-render the clan list from this payload:', refreshed);
+   *   },
    * });
-   * ```
    *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getMiniGames().then((result) => {
-   *      console.log(result);
-   * });
+   * console.log('[smartico] user is', result.user_clan_id == null ? 'clanless' : 'in clan ' + result.user_clan_id);
+   *
+   * // Cooldown handling — affects ALL clans, not a specific one.
+   * if (result.cooldown_until) {
+   *   const cooldownEndsUtc = new Date(result.cooldown_until + 'Z');
+   *   console.log('[smartico] switch-cooldown active — disable all Join buttons until', cooldownEndsUtc.toLocaleString(),
+   *     '(local). Render the cooldown end on the disabled button label.');
+   * }
+   *
+   * // Render clans — already sorted by rating_position ASC.
+   * for (const clan of result.clans) {
+   *   const isMine = clan.clan_id === result.user_clan_id;
+   *   const isFull = clan.member_count >= clan.capacity_limit;
+   *
+   *   if (isMine) {
+   *     console.log('[smartico] highlight clan', clan.clan_id, 'as "Your clan"; CTA label "Your clan", no-op');
+   *   } else if (result.cooldown_until) {
+   *     console.log('[smartico] clan', clan.clan_id, '— Join blocked by user cooldown; show disabled button with cooldown end date');
+   *   } else if (isFull) {
+   *     console.log('[smartico] clan', clan.clan_id, '— Clan full; show disabled "Clan is full" button');
+   *   } else {
+   *     const label = clan.entry_fee_amount === 0 || clan.entry_fee_currency_type_id === 3
+   *       ? 'Join free'
+   *       : `Join (${clan.entry_fee_amount} ${['Points','Gems','Diamonds'][clan.entry_fee_currency_type_id]})`;
+   *     console.log('[smartico] clan', clan.clan_id, '— render enabled Join button labelled', label);
+   *   }
+   * }
+   *
+   * // After a successful joinClan(), re-call getClans manually — no push refresh.
+   * // const r = await window._smartico.api.joinClan(targetClanId);
+   * // if (r.errCode === 0) await window._smartico.api.getClans();
    * ```
-   *
    */
-  async getMiniGames({
+  async getClans({
     onUpdate
   } = {}) {
     if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.Saw, onUpdate);
+      this.onUpdateCallback.set(onUpdateContextKey.Clans, onUpdate);
     }
-    return OCache.use(onUpdateContextKey.Saw, ECacheContext.WSAPI, () => this.api.sawGetTemplatesT(this.userExtId), CACHE_DATA_SEC);
+    return OCache.use(onUpdateContextKey.Clans, ECacheContext.WSAPI, () => this.api.clansGetListT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Returns the list of mini-games based on the provided parameters. "Limit" and "offset" indicate the range of items to be fetched.
-   * The maximum number of items per request is limited to 20.
-   * You can leave this params empty and by default it will return list of mini-games ranging from 0 to 20.
-   * The returned list of mini-games history is cached for 30 seconds.
-   *
-   * **Example**:
+   * Returns the full detail of a single clan — adds the ranked
+   * `members[]` roster and a fresh `cooldown_until` on top of the same
+   * fields exposed on a `TClan` list entry. Use this to power a clan
+   * detail screen / popup after the user picks an item from
+   * {@link getClans}.
+   *
+   * Each call is a fresh server round-trip — there is no client cache
+   * and no push event refreshes detail state. Re-call to refresh.
+   *
+   * @remarks
+   * **Preconditions**
+   * Pass a valid `clanId` (typically read from
+   * `TClans.clans[i].clan_id` returned by {@link getClans}). The
+   * method works standalone — `getClans()` is not required first —
+   * but is the only stable source of valid IDs.
+   *
+   * **Refresh model**
+   * - **No subscription.** One-shot promise.
+   * - **No client cache.** Every call sends a network request.
+   * - **No push event** refreshes the detail. Member-join, kick, or
+   *   contribution-score changes require a fresh `getClanInfo` call.
+   *
+   * **Returned shape — beyond `TClan`**
+   * `TClanInfo` adds two things on top of the same identity / capacity
+   * / fee / rating fields you'd see on a `TClan` list entry:
+   * 1. A ranked `members[]` array — each entry carries `user_id`,
+   *    `public_username`, `avatar_id` / `avatar_real_id`, the resolved
+   *    `avatar_url`, the member's `position` (rank within this clan),
+   *    `contribution_score`, the `is_me` flag identifying the current
+   *    user's row, and the optional `clean_ext_user_id`. The server
+   *    orders members by score DESC (i.e. `position` ASC); no
+   *    client-side re-sort is required.
+   * 2. A fresh `cooldown_until` on the clan info itself. This is the
+   *    SAME user-level cooldown as `TClans.cooldown_until` (the
+   *    cooldown is global to the user, not per clan) — but `getClans`
+   *    returns a value cached for up to 30 s while `getClanInfo`
+   *    always returns the current value. If the list-cached cooldown
+   *    has just expired, this detail call will reflect it first.
+   *
+   * **Username display**: in the default Smartico UI, member rows use
+   * `public_username`. Some surfaces (e.g. the tournament clan
+   * drill-down) prefer `clean_ext_user_id` as the primary display
+   * with `public_username` as fallback — pick the convention that
+   * matches your product's identity model.
+   *
+   * **Idempotency**: safe. Read-only.
+   *
+   * **Side effects**: none — pure metadata read.
+   *
+   * **UI guidance**: see [UI Guide — `getClanInfo`](../../docs/ui/clans/UIGuide_getClanInfo.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param clanId  The clan ID from `TClans.clans[i].clan_id`.
+   * @returns       Promise resolving to `TClanInfo`. Rejects if the
+   *                clan ID is invalid or the user lacks visibility
+   *                for it.
+   *
+   * @example
+   * ```ts
+   * const result = await window._smartico.api.getClans();
+   * const clan = result.clans[0];
+   *
+   * console.log('[smartico] loading detail for clan', clan.clan_id);
+   * const detail = await window._smartico.api.getClanInfo(clan.clan_id);
+   *
+   * console.log('[smartico] render detail with', detail.members.length, 'members');
+   *
+   * // Find current user's row to power a sticky "me" footer.
+   * const meRow = detail.members.find(m => m.is_me);
+   * if (meRow) {
+   *   console.log('[smartico] current user rank in this clan:', meRow.position,
+   *     'contribution:', meRow.contribution_score, '— render sticky my-member footer');
+   * }
+   *
+   * // Resolve Join CTA state using the detail's cooldown (always fresh).
+   * const isMyClan = detail.clan_id === result.user_clan_id;
+   * const inCooldown = detail.cooldown_until != null;
+   * const isFull = detail.member_count >= detail.capacity_limit;
+   * if (isMyClan) {
+   *   console.log('[smartico] this is the user\'s clan — render disabled "Your clan" button');
+   * } else if (inCooldown) {
+   *   const ends = new Date(detail.cooldown_until + 'Z');
+   *   console.log('[smartico] user is in clan-switch cooldown until', ends.toLocaleString(),
+   *     '— render disabled cooldown button');
+   * } else if (isFull) {
+   *   console.log('[smartico] clan is full — render disabled "Clan is full" button');
+   * } else {
+   *   console.log('[smartico] joinable — render enabled Join button');
+   * }
    * ```
-   * _smartico.api.getMiniGamesHistory().then((result) => {
-   *      console.log(result);
-   * });
+   */
+  async getClanInfo(clanId) {
+    return this.api.clansGetInfoT(this.userExtId, clanId);
+  }
+  /**
+   * Joins (or switches into) a clan on behalf of the current user. For
+   * paid clans (`entry_fee_amount > 0`), the user's balance for the
+   * matching currency is debited synchronously before the response
+   * returns. If the user is already in a clan, this is treated as an
+   * atomic clan-switch (deactivate old membership + insert new + debit
+   * fee, all in one transaction — the user is never observably
+   * clanless).
+   *
+   * A successful response (`errCode === 0`) means: membership is
+   * persisted, the fee (if any) has been debited, the user's
+   * switch-cooldown has restarted, and a clan-joined CRM event has
+   * fired server-side.
+   *
+   * @remarks
+   * **Result shape note**: `TClanJoinResult` uses `errCode` / `errMsg`
+   * (camelCase) — different from most other SDK result types in this
+   * library which use `err_code` / `err_message` (snake_case). Branch
+   * on the camelCase keys when reading this method's result.
+   *
+   * **Preconditions**
+   * Read the candidate from {@link getClans} and gate the call on
+   * `clan.member_count < clan.capacity_limit`, `cooldown_until == null`
+   * (on the `TClans` payload — the cooldown is user-level, not
+   * per-clan), and the user's balance for `entry_fee_currency_type_id`
+   * being at least `entry_fee_amount` (free clans bypass this check).
+   * The SDK forwards the call unconditionally — calling without
+   * satisfying these will most likely return one of the error codes
+   * below.
+   *
+   * **Error codes** (in `errCode`, typed as {@link JoinClanErrorCode})
+   * - `0` (`JOIN_CLAN_OK`) — success; membership persisted, fee
+   *   debited, cooldown restarted.
+   * - `1000` (`JOIN_CLAN_INVALID_PARAMETERS`) — request body missing
+   *   `clan_id`. Should not occur via the SDK; treat as a programming
+   *   error.
+   * - `1001` (`JOIN_CLAN_NOT_FOUND`) — clan doesn't exist for this
+   *   label, OR the clan is archived / in draft state. The server
+   *   merges "missing" and "archived" into this single code. Refresh
+   *   `getClans()` and remove the entry from the UI.
+   * - `1002` (`JOIN_CLAN_FULL`) — capacity reached between the list
+   *   fetch and the join click (`member_count >= capacity_limit` at
+   *   the server's atomic check). Refresh the list — the button will
+   *   become "Clan is full".
+   * - `1003` (`JOIN_CLAN_INSUFFICIENT_FUNDS`) — insufficient balance
+   *   for the clan's entry fee. A single code covers all three
+   *   currencies (points / gems / diamonds); read
+   *   `clan.entry_fee_currency_type_id` to identify which currency
+   *   the user is short on. Show an insufficient-balance UI naming
+   *   the deficit.
+   * - `1004` (`JOIN_CLAN_SEGMENT_MISMATCH`) — user does not meet the
+   *   clan's entry segment or numeric conditions. There is no
+   *   client-side pre-guard for this — surface a gating message.
+   * - `1005` (`JOIN_CLAN_USER_IS_NOT_IN_CLAN`) — this method NEVER
+   *   returns `1005`. The code is shared with the tournament
+   *   registration error space and fires only on
+   *   {@link registerInTournament} responses when a clan-based
+   *   tournament requires the user to be in a clan first.
+   * - `1006` (`JOIN_CLAN_COOLDOWN_ACTIVE`) — user is inside the
+   *   switch-cooldown window from a previous clan join (default
+   *   7 days, configurable per label). Surface the
+   *   `TClans.cooldown_until` expiry in the disabled CTA.
+   * - `1007` (`JOIN_CLAN_ARCHIVED`) — defined on the public enum but
+   *   the server does NOT emit this code in practice (archived clans
+   *   are reported as `1001`). Handle it as a synonym for `1001`
+   *   defensively, but do not rely on it.
+   * - `1011` (`JOIN_CLAN_JOINED_AFTER_TOURNAMENT_START`) — this
+   *   method does NOT return `1011` directly. The code fires on
+   *   {@link registerInTournament} responses when the user joined
+   *   their current clan after the tournament started AND already
+   *   has tournament scores.
+   * - other non-zero — generic server error. Surface `errMsg` if any.
+   *
+   * **Idempotency**: NOT safe — and notably dangerous. Calling
+   * `joinClan` with the user's CURRENT `clanId` does NOT short-circuit
+   * server-side; the call is treated as a clan-switch to the same
+   * clan. If the label's cooldown is non-zero (the default), the
+   * second call returns `1006`. If the cooldown is configured to
+   * zero, the second call will deduct the entry fee AGAIN, deactivate
+   * the membership, and re-insert it. The SDK does NOT enforce an
+   * in-flight lock. Consumers MUST guard the call site against
+   * double-clicks (set a local "joining" flag on click, clear it on
+   * response) AND short-circuit when the user is already in the
+   * target clan.
+   *
+   * **Refresh after success (and after failure)**
+   * The SDK does NOT automatically refresh the {@link getClans} cache
+   * after a join. Manually re-call `getClans()` on success to pick up
+   * the new `user_clan_id`, refreshed `member_count`, and the new
+   * `cooldown_until` value. Until you do, the cached `TClans` payload
+   * is stale.
+   *
+   * **Side effects** (consumer-observable on success)
+   * - Entry-fee currency balance decreases by `entry_fee_amount`
+   *   (visible on the next {@link getUserProfile} refresh / via the
+   *   user-properties update channel).
+   * - The user's clan membership row is created (or replaced, on a
+   *   switch). `member_count` on the new clan increments by 1; on a
+   *   switch, the old clan's `member_count` decrements by 1 in the
+   *   same transaction.
+   * - The user's switch-cooldown restarts at the join time (the
+   *   `TClans.cooldown_until` field on the next list fetch reflects
+   *   the new expiry).
+   * - Server-side CRM analytics fire (clan-joined event, currency-
+   *   deducted event for paid clans). These surface only as
+   *   server-side traces; the SDK consumer observes them indirectly
+   *   via balance / membership refresh.
+   *
+   * **UI guidance**: see [UI Guide — `joinClan`](../../docs/ui/clans/UIGuide_joinClan.md).
+   *
+   * **Visitor mode**: not supported. The server rejects the request
+   * for unauthenticated sessions.
+   *
+   * @param clanId  The clan ID from `TClans.clans[i].clan_id` (or
+   *                `TClanInfo.clan_id`).
+   * @returns `{ errCode, errMsg }`; success when `errCode === 0`.
+   *          Note camelCase keys (see "Result shape note" above).
+   *
+   * @example
+   * ```ts
+   * const result = await window._smartico.api.getClans();
+   * const target = result.clans.find(c => c.clan_id === clanId);
+   *
+   * if (!target) {
+   *   console.log('[smartico] clan not in current list — refresh getClans and retry');
+   *   return;
+   * }
+   * if (target.clan_id === result.user_clan_id) {
+   *   console.log('[smartico] user is already in this clan — short-circuit; do NOT call joinClan again, the server will treat it as a switch and may re-deduct the fee');
+   *   return;
+   * }
+   * if (result.cooldown_until) {
+   *   console.log('[smartico] user is in cooldown — disable Join until', new Date(result.cooldown_until + 'Z').toLocaleString());
+   *   return;
+   * }
+   * if (target.member_count >= target.capacity_limit) {
+   *   console.log('[smartico] clan is full — disable Join');
+   *   return;
+   * }
+   *
+   * console.log('[smartico] join starting — set in-flight flag, show loading dots on Join button, keep modal open');
+   * const r = await window._smartico.api.joinClan(target.clan_id);
+   * console.log('[smartico] join response received — clear in-flight flag');
+   *
+   * if (r.errCode === 0) {
+   *   console.log('[smartico] joined successfully — refresh getClans to pick up the new user_clan_id, member_count, and cooldown_until');
+   *   await window._smartico.api.getClans();
+   * } else if (r.errCode === 1002) {
+   *   console.error('[smartico] clan is full — refresh list, hide the Join CTA on the now-full clan');
+   * } else if (r.errCode === 1003) {
+   *   const currencyLabel = ['points', 'gems', 'diamonds'][target.entry_fee_currency_type_id] ?? 'currency';
+   *   console.error('[smartico] insufficient', currencyLabel, '— need', target.entry_fee_amount);
+   * } else if (r.errCode === 1004) {
+   *   console.error('[smartico] user does not meet segment / entry conditions — show a gating message');
+   * } else if (r.errCode === 1006) {
+   *   console.error('[smartico] cooldown active — surface the cooldown_until from getClans:', result.cooldown_until);
+   * } else if (r.errCode === 1001) {
+   *   console.error('[smartico] clan not found or archived — refresh list and remove from UI');
+   * } else {
+   *   console.error('[smartico] join failed — show a generic error toast with this message:', r.errMsg);
+   * }
    * ```
-   *
-   * **Visitor mode: not supported**
    */
-  async getMiniGamesHistory({
-    limit,
-    offset,
-    saw_template_id
-  }) {
-    return OCache.use(onUpdateContextKey.SAWHistory, ECacheContext.WSAPI, () => this.api.getSawWinningHistoryT(this.userExtId, limit, offset, saw_template_id), CACHE_DATA_SEC);
+  async joinClan(clanId) {
+    return this.api.clanJoin(this.userExtId, clanId);
   }
-  /**
-   * Plays the specified by template_id mini-game on behalf of user and returns prize_id or err_code
-   * After playMiniGame is called, you can call getMiniGames to get the list of mini-games.The returned list of mini-games is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call playMiniGame with a new onUpdate callback, the old one will be overwritten by the new one.
-   * The onUpdate callback will be called on available spin count change, if mini-game has increasing jackpot per spin or won prize is spin/jackpot and if max count of the available user spins equals one, also if the spins were issued to the user manually in the BO. Updated templates will be passed to onUpdate callback.
+  async updateClans() {
+    const payload = await this.api.clansGetListT(this.userExtId);
+    this.updateEntity(onUpdateContextKey.Clans, payload);
+  }
+}
+
+/** @group Jackpots */
+class WSAPIJackpots extends WSAPIClans {
+  constructor(...args) {
+    super(...args);
+    /** @hidden */
+    this.jackpotGetSignature = '';
+  }
+  async jackpotClearCache() {
+    OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.Jackpots);
+    OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.Pots);
+    OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.JackpotWinners);
+  }
+  /** Returns list of Jackpots that are active in the system and matching to the filter definition.
+   * If filter is not provided, all active jackpots will be returned.
+   * Filter can be used to get jackpots related to specific game or specific jackpot template.
+   * 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
    *
    * **Example**:
    * ```
-   * _smartico.api.playMiniGame(55).then((result) => {
+   * _smartico.api.jackpotGet({ related_game_id: 'wooko-slot' }).then((result) => {
    *      console.log(result);
    * });
    * ```
    *
-   * **Visitor mode: not supported**
+   * **Example in the Visitor mode**:
+   * ```
+   * _smartico.vapi('EN').jackpotGet({ related_game_id: 'wooko-slot' }).then((result) => {
+   *      console.log(result);
+   * });
+   * ```
    */
-  async playMiniGame(template_id, {
-    onUpdate
-  } = {}) {
-    if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.Saw, onUpdate);
+  async jackpotGet(filter) {
+    var _this = this;
+    const signature = `${filter == null ? void 0 : filter.jp_template_id}:${filter == null ? void 0 : filter.related_game_id}`;
+    if (signature !== this.jackpotGetSignature) {
+      this.jackpotGetSignature = signature;
+      this.jackpotClearCache();
     }
-    const r = await this.api.sawSpinRequest(this.userExtId, template_id);
-    this.api.doAcknowledgeRequest(this.userExtId, r.request_id);
-    const o = {
-      err_code: r.errCode,
-      err_message: r.errMsg,
-      prize_id: r.saw_prize_id
-    };
-    return o;
+    let jackpots = [];
+    let pots = [];
+    jackpots = await OCache.use(onUpdateContextKey.Jackpots, ECacheContext.WSAPI, async function () {
+      const _jackpots = await _this.api.jackpotGet(_this.userExtId, filter);
+      const _pots = _jackpots.items.map(jp => jp.pot);
+      _jackpots.items.forEach(jp => {
+        jp.jp_public_meta.custom_data = IntUtils.JsonOrText(jp.jp_public_meta.custom_data);
+      });
+      OCache.set(onUpdateContextKey.Pots, _pots, ECacheContext.WSAPI, JACKPOT_POT_CACHE_SEC);
+      return _jackpots.items;
+    }, JACKPOT_TEMPLATE_CACHE_SEC);
+    if (jackpots.length > 0) {
+      pots = await OCache.use(onUpdateContextKey.Pots, ECacheContext.WSAPI, async function () {
+        const jp_template_ids = jackpots.map(jp => jp.jp_template_id);
+        return (await _this.api.potGet(_this.userExtId, {
+          jp_template_ids
+        })).items;
+      }, JACKPOT_POT_CACHE_SEC);
+    }
+    return jackpots.map(jp => {
+      let _jp = _extends({}, jp, {
+        pot: pots.find(p => p.jp_template_id === jp.jp_template_id)
+      });
+      return _jp;
+    });
   }
   /**
-   * Sends the acknowledge request with specific client_request_id from minigame history in order to claim prize
+   * Opt-in currently logged in user to the jackpot with the specified jp_template_id.
+   * You may call jackpotGet method after doing optin to see that user is opted in to the jackpot.
+   *
    * **Example**:
    * ```
-   * _smartico.api.miniGameWinAcknowledgeRequest('2a189322-31bb-4119-b943-bx7868ff8dc3').then((result) => {
-   *      console.log(result);
+   * _smartico.api.jackpotOptIn({ jp_template_id: 123 }).then((result) => {
+   *      console.log('Opted in to the jackpot');
    * });
    * ```
+   *
+   * **Visitor mode: not supported**
+   *
    */
-  async miniGameWinAcknowledgeRequest(request_id) {
-    return this.api.doAcknowledgeRequest(this.userExtId, request_id);
+  async jackpotOptIn(filter) {
+    if (!filter.jp_template_id) {
+      throw new Error('jp_template_id is required in jackpotOptIn');
+    }
+    const result = await this.api.jackpotOptIn(this.userExtId, filter);
+    return result;
   }
   /**
-   * Plays the specified by template_id mini-game on behalf of user spin_count times and returns array of the prizes
-   * After playMiniGameBatch is called, you can call getMiniGames to get the list of mini-games. The returned list of mini-games is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call playMiniGameBatch with a new onUpdate callback, the old one will be overwritten by the new one.
-   * The onUpdate callback will be called on available spin count change, if mini-game has increasing jackpot per spin or won prize is spin/jackpot and if max count of the available user spins equals one, also if the spins were issued to the user manually in the BO. Updated templates will be passed to onUpdate callback.
+   * Opt-out currently logged in user from the jackpot with the specified jp_template_id.
+   * You may call jackpotGet method after doing optout to see that user is not opted in to the jackpot.
    *
    * **Example**:
    * ```
-   * _smartico.api.playMiniGameBatch(55, 10).then((result) => {
-   *      console.log(result);
+   * _smartico.api.jackpotOptOut({ jp_template_id: 123 }).then((result) => {
+   *      console.log('Opted out from the jackpot');
    * });
    * ```
+   *
    * **Visitor mode: not supported**
+   *
    */
-  async playMiniGameBatch(template_id, spin_count, {
-    onUpdate
-  } = {}) {
-    if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.Saw, onUpdate);
+  async jackpotOptOut(filter) {
+    if (!filter.jp_template_id) {
+      throw new Error('jp_template_id is required in jackpotOptOut');
     }
-    const response = await this.api.sawSpinBatchRequest(this.userExtId, template_id, spin_count);
-    const request_ids = response.results.map(result => result.request_id);
-    this.api.doAcknowledgeBatchRequest(this.userExtId, request_ids);
-    const o = response.results.map(result => ({
-      errCode: result.errCode,
-      errMessage: result.errMsg,
-      saw_prize_id: result.saw_prize_id,
-      jackpot_amount: result.jackpot_amount,
-      first_spin_in_period: result.first_spin_in_period
-    }));
-    return o;
+    const result = await this.api.jackpotOptOut(this.userExtId, filter);
+    return result;
   }
   /**
-   * Requests an opt-in for the specified mission_id. Returns the err_code.
+   * Returns jackpot winners for the given `jp_template_id` (paginated on the server).
+   * Default page size on the wire is 20; use `limit`, `offset`, and repeated calls to load more.
+   * The full protocol response also includes `has_more`; this method returns only the `winners` array.
+   *
+   * **Example**:
+   * ```
+   * _smartico.api.getJackpotWinners({
+   *      jp_template_id: 123,
+   * }).then((result) => {
+   *      console.log(result);
+   * });
+   * ```
    *
    * **Visitor mode: not supported**
+   *
+   * @param params - Jackpot winners parameters
+   * @param params.jp_template_id - Jackpot template id (required; throws if missing)
+   * @param params.limit - Page size (server default 20 when omitted)
+   * @param params.offset - Offset into the winner list
    */
-  async requestMissionOptIn(mission_id) {
-    const r = await this.api.missionOptIn(this.userExtId, mission_id);
-    const o = {
-      err_code: r.errCode,
-      err_message: r.errMsg
-    };
-    return o;
+  async getJackpotWinners({
+    limit,
+    offset,
+    jp_template_id
+  }) {
+    return OCache.use(onUpdateContextKey.JackpotWinners + jp_template_id, ECacheContext.WSAPI, () => this.api.getJackpotWinnersT(this.userExtId, limit, offset, jp_template_id), JACKPOT_WINNERS_CACHE_SEC);
   }
   /**
-   * Request for claim reward for the specified mission id. Returns the err_code.
+   * Returns the eligible games for the jackpot with the specified jp_template_id.
+   *
+   * **Example**:
+   * ```
+   * _smartico.api.getJackpotEligibleGames({ jp_template_id: 123 }).then((result) => {
+   *      console.log(result);
+   * });
+   * ```
    *
    * **Visitor mode: not supported**
+   *
    */
-  async requestMissionClaimReward(mission_id, ach_completed_id) {
-    const r = await this.api.missionClaimPrize(this.userExtId, mission_id, ach_completed_id);
-    const o = {
-      err_code: r.errCode,
-      err_message: r.errMsg
-    };
-    return o;
+  async getJackpotEligibleGames({
+    jp_template_id,
+    onUpdate
+  }) {
+    if (onUpdate) {
+      this.onUpdateCallback.set(onUpdateContextKey.JackpotEligibleGames, onUpdate);
+    }
+    return OCache.use(onUpdateContextKey.JackpotEligibleGames + jp_template_id, ECacheContext.WSAPI, () => this.api.getJackpotEligibleGamesT(this.userExtId, {
+      jp_template_id
+    }), JACKPOT_ELIGIBLE_GAMES_CACHE_SEC);
+  }
+}
+
+/** @group Raffles */
+class WSAPIRaffles extends WSAPIJackpots {
+  async updateRaffles() {
+    const payload = await this.api.getRafflesT(this.userExtId);
+    this.updateEntity(onUpdateContextKey.Raffles, payload);
   }
-  /** Returns all the active instances of tournaments
-   * The returned list is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call getTournamentsList with a new onUpdate callback, the old one will be overwritten by the new one.
-   * The onUpdate callback will be called when the user has registered in a tournament. Updated list will be passed to onUpdate callback.
+  /**
+   * Returns the list of Raffles available for user
+   * The returned list of Raffles is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call getRaffles with a new onUpdate callback, the old one will be overwritten by the new one.
+   * The onUpdate callback will be called on claiming prize.  Updated Raffles will be passed to onUpdate callback.
    *
    * **Example**:
+   *
    * ```
-   * _smartico.api.getTournamentsList().then((result) => {
+   * _smartico.api.getRaffles().then((result) => {
    *      console.log(result);
    * });
    * ```
    *
    * **Example in the Visitor mode**:
+   *
    * ```
-   * _smartico.vapi('EN').getTournamentsList().then((result) => {
+   * _smartico.vapi('EN').getRaffles().then((result) => {
    *      console.log(result);
    * });
    * ```
-   * */
-  async getTournamentsList({
-    onUpdate
-  } = {}) {
-    if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.TournamentList, onUpdate);
-    }
-    return OCache.use(onUpdateContextKey.TournamentList, ECacheContext.WSAPI, () => this.api.tournamentsGetLobbyT(this.userExtId), CACHE_DATA_SEC);
-  }
-  /**
-   * Returns clans list payload for the current user.
-   * The returned payload is cached for 30 seconds.
-   * If onUpdate is passed, it will be called when clans response is received.
    *
-   * **Visitor mode: not supported**
    */
-  async getClans({
+  async getRaffles({
     onUpdate
   } = {}) {
     if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.Clans, onUpdate);
+      this.onUpdateCallback.set(onUpdateContextKey.Raffles, onUpdate);
     }
-    return OCache.use(onUpdateContextKey.Clans, ECacheContext.WSAPI, () => this.api.clansGetListT(this.userExtId), CACHE_DATA_SEC);
-  }
-  /**
-   * Returns detailed information for a specific clan including its members.
-   *
-   * **Visitor mode: not supported**
-   */
-  async getClanInfo(clanId) {
-    return this.api.clansGetInfoT(this.userExtId, clanId);
+    return OCache.use(onUpdateContextKey.Raffles, ECacheContext.WSAPI, () => this.api.getRafflesT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Joins a clan on behalf of the current user.
+   * Returns draw run for provided raffle_id and run_id.
+   * You can pass winners_from and winners_to parameters to get a specific range of winners. Default is 0-20.
    *
-   * **Visitor mode: not supported**
-   */
-  async joinClan(clanId) {
-    return this.api.clanJoin(this.userExtId, clanId);
-  }
-  /**
-   * Returns detailed information for a specific tournament instance; the response includes tournament info and the leaderboard of players
    *
    * **Example**:
-   * ```
-   * _smartico.api.getTournamentsList().then((result) => {
-   *      if (result.length > 0) {
-   *         _smartico.api.getTournamentInstanceInfo(result[0].instance_id).then((result) => {
-   *             console.log(result);
-   *        });
-   *     }
+   *
+   * ```javascript
+   * _smartico.api.getRaffleDrawRun({raffle_id: 156, run_id: 145}).then((result) => {
+   *      console.log(result);
    * });
    * ```
    *
    * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getTournamentsList().then((result) => {
-   *      if (result.length > 0) {
-   *         _smartico.vapi('EN').getTournamentInstanceInfo(result[0].instance_id).then((result) => {
-   *             console.log(result);
-   *        });
-   *     }
+   *
+   *
+   * ```javascript
+   * _smartico.vapi('EN').getRaffleDrawRun({ raffle_id: 156, run_id: 145 }).then((result) => {
+   *      console.log(result);
    * });
    * ```
+   *
    */
-  async getTournamentInstanceInfo(tournamentInstanceId) {
-    return this.api.tournamentsGetInfoT(this.userExtId, tournamentInstanceId);
+  async getRaffleDrawRun(props) {
+    if (!props.raffle_id || !props.run_id) {
+      throw new Error('both raffle_id and run_id are required');
+    }
+    return await this.api.getRaffleDrawRunT(this.userExtId, props.raffle_id, props.run_id, props.winners_from, props.winners_to);
   }
   /**
-   * Returns the players of a specific clan in a clan-based tournament.
+   * Returns history of draw runs for the provided raffle_id and draw_id, if the draw_id is not provided will return history of all the draws for the provided raffle_id
    *
-   * **Visitor mode: not supported**
-   */
-  async getClanTournamentPlayers(tournamentInstanceId, clanId) {
-    return this.api.clanTournamentGetPlayers(this.userExtId, tournamentInstanceId, clanId);
-  }
-  /**
-   * Requests registration for the specified tournament instance. Returns the err_code.
-   *
-   * **Visitor mode: not supported**
-   */
-  async registerInTournament(tournamentInstanceId) {
-    const r = await this.api.registerInTournament(this.userExtId, tournamentInstanceId);
-    const o = {
-      err_code: r.errCode,
-      err_message: r.errMsg
-    };
-    return o;
-  }
-  /**
-   * 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.
-   * For example, if the type is Weekly and getPreviousPeriod is true, a leaderboard for the previous week will be returned.
    *
    * **Example**:
-   * ```
-   * _smartico.api.getLeaderBoard(1).then((result) => {
-   *     console.log(result);
+   *
+   * ```javascript
+   * _smartico.api.getRaffleDrawRunsHistory({ raffle_id: 156, draw_id: 432 }).then((result) => {
+   *      console.log(result);
    * });
    * ```
    *
    * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getLeaderBoard(1).then((result) => {
-   *    console.log(result);
+   *
+   * ```javascript
+   * _smartico.vapi('EN').getRaffleDrawRunsHistory({ raffle_id: 156, draw_id: 432 }).then((result) => {
+   *      console.log(result);
    * });
    * ```
-   */
-  async getLeaderBoard(periodType, getPreviousPeriod) {
-    return OCache.use(onUpdateContextKey.LeaderBoards, ECacheContext.WSAPI, () => this.api.leaderboardsGetT(this.userExtId, periodType, getPreviousPeriod), CACHE_DATA_SEC);
-  }
-  /** Returns inbox messages based on the provided parameters. "From" and "to" indicate the range of messages to be fetched.
-   * The maximum number of messages per request is limited to 20.
-   * An indicator "onlyFavorite" can be passed to get only messages marked as favorites.
-   * An indicator "read_status" can be passed to get only messages marked as read or unread.
-   * You can leave this params empty and by default it will return list of messages ranging from 0 to 20.
-   * This function returns a list of messages without the body of each message.
-   * To get the body of the message you need to call getInboxMessageBody function and pass the message guid contained in each message of this request.
-   * All other action like mark as read, favorite, delete, etc. can be done using this message GUID.
-   * The "onUpdate" callback will be triggered when the user receives a new message. It will provide an updated list of messages, ranging from 0 to 20, to the onUpdate callback function.
    *
-   * **Visitor mode: not supported**
-   *
-   * @param params
    */
-  async getInboxMessages({
-    from,
-    to,
-    onlyFavorite,
-    categoryId,
-    read_status,
-    onUpdate
-  } = {}) {
-    if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.InboxMessages, onUpdate);
+  async getRaffleDrawRunsHistory(props) {
+    const res = await this.api.getRaffleDrawRunsHistory(this.userExtId, props);
+    if (!props.raffle_id) {
+      throw new Error('raffle_id is required');
     }
-    return await this.api.getInboxMessagesT(this.userExtId, from, to, onlyFavorite, categoryId, read_status);
+    return drawRunHistoryTransform(res);
   }
   /**
-   * Returns inbox unread count.
+   * Returns `err_code` and `err_message` after the call; `err_code` 0 means the request succeeded.
    *
-   * **Visitor mode: not supported**
-   * @param params
-   */
-  async getInboxUnreadCount({
-    onUpdate
-  } = {}) {
-    if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.InboxUnreadCount, onUpdate);
-    }
-    return OCache.use(onUpdateContextKey.InboxUnreadCount, ECacheContext.WSAPI, () => this.api.getInboxUnreadCountT(this.userExtId), CACHE_DATA_SEC);
-  }
-  /**
-   * Returns the message body of the specified message guid.
    *
-   * **Visitor mode: not supported**
-   */
-  async getInboxMessageBody(messageGuid) {
-    return await this.api.getInboxMessageBodyT(messageGuid);
-  }
-  /**
-   * Requests to mark inbox message with specified guid as read
+   * **Example**:
    *
-   * **Visitor mode: not supported**
-   */
-  async markInboxMessageAsRead(messageGuid) {
-    const r = await this.api.markInboxMessageRead(this.userExtId, messageGuid);
-    return {
-      err_code: r.errCode,
-      err_message: r.errMsg
-    };
-  }
-  /**
-   * Requests to mark all inbox messages as read
+   * ```javascript
+   * _smartico.api.claimRafflePrize({won_id:251}).then((result) => {
+   *      console.log(result);
+   * });
+   * ```
    *
-   * **Visitor mode: not supported**
-   */
-  async markAllInboxMessagesAsRead() {
-    const r = await this.api.markAllInboxMessageRead(this.userExtId);
-    return {
-      err_code: r.errCode,
-      err_message: r.errMsg
-    };
-  }
-  /**
-   * Requests to mark inbox message with specified guid as favorite. Pass mark true to add message to favorite and false to remove.
+   * **Example in the Visitor mode**:
    *
-   * **Visitor mode: not supported**
-   */
-  async markUnmarkInboxMessageAsFavorite(messageGuid, mark) {
-    const r = await this.api.markUnmarkInboxMessageAsFavorite(this.userExtId, messageGuid, mark);
-    return {
-      err_code: r.errCode,
-      err_message: r.errMsg
-    };
-  }
-  /**
-   * Requests to delete inbox message
+   * ```javascript
+   * _smartico.vapi('EN').claimRafflePrize({ won_id: 251 }).then((result) => {
+   *      console.log(result);
+   * });
+   * ```
    *
-   * **Visitor mode: not supported**
    */
-  async deleteInboxMessage(messageGuid) {
-    const r = await this.api.deleteInboxMessage(this.userExtId, messageGuid);
-    return {
-      err_code: r.errCode,
-      err_message: r.errMsg
-    };
+  async claimRafflePrize(props) {
+    if (!props.won_id) {
+      throw new Error('won_id is required');
+    }
+    const res = await this.api.claimRafflePrize(this.userExtId, {
+      won_id: props.won_id
+    });
+    return raffleClaimPrizeResponseTransform(res);
   }
   /**
-   * Requests to delete all inbox messages
+   * Requests an opt-in for the specified raffle. Returns the err_code.
    *
    * **Visitor mode: not supported**
    */
-  async deleteAllInboxMessages() {
-    const r = await this.api.deleteAllInboxMessages(this.userExtId);
+  async requestRaffleOptin(props) {
+    if (!props.raffle_id) {
+      throw new Error('raffle_id is required');
+    }
+    if (!props.draw_id) {
+      throw new Error('draw_id is required');
+    }
+    if (!props.raffle_run_id) {
+      throw new Error('raffle_run_id is required');
+    }
+    const r = await this.api.raffleOptin(this.userExtId, props);
     return {
       err_code: r.errCode,
       err_message: r.errMsg
     };
   }
+}
+
+/** @group MiniGames */
+class WSAPIMiniGames extends WSAPIRaffles {
   /**
-   * Requests translations for the given language. Returns the object including translation key/translation value pairs. All possible translation keys defined in the back office.
-   */
-  async getTranslations(lang_code) {
-    const r = await this.api.getTranslationsT(this.userExtId, lang_code, []);
-    return {
-      translations: r.translations
-    };
-  }
-  /**
-   * Reports an impression event for an engagement (when engagement content is displayed to the user).
-   * Use this method to track when users view engagement content such as inbox messages, popups.
-   * When using for Inbox cases, you need to use message guid as engagement_uid, and pass 31 as activityType.
+   * Returns the list of mini-games configured for the current user (not filtered by spin availability or Widget visibility).
+   * The returned list of mini-games is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call getMiniGames with a new onUpdate callback, the old one will be overwritten by the new one.
+   * The onUpdate callback will be called on available spin count change, if mini-game has increasing jackpot per spin or won prize is spin/jackpot and if max count of the available user spins equals one, also if the spins were issued to the user manually in the BO. Updated templates will be passed to onUpdate callback.
    *
    * **Example**:
    * ```
-   * _smartico.api.reportImpressionEvent({
-   *      engagement_uid: 'abc123-def456',
-   *      activityType: 31 // Inbox
+   * _smartico.api.getMiniGames().then((result) => {
+   *      console.log(result);
    * });
    * ```
    *
-   * **Visitor mode: not supported**
+   * **Example in the Visitor mode**:
+   * ```
+   * _smartico.vapi('EN').getMiniGames().then((result) => {
+   *      console.log(result);
+   * });
+   * ```
    *
-   * @param params - Event parameters
-   * @param params.engagement_uid - Unique identifier for the engagement
-   * @param params.activityType - Type of engagement activity (Popup=30, Inbox=31)
    */
-  reportImpressionEvent({
-    engagement_uid,
-    activityType
-  }) {
-    this.api.reportEngagementImpression(this.userExtId, engagement_uid, activityType);
+  async getMiniGames({
+    onUpdate
+  } = {}) {
+    if (onUpdate) {
+      this.onUpdateCallback.set(onUpdateContextKey.Saw, onUpdate);
+    }
+    return OCache.use(onUpdateContextKey.Saw, ECacheContext.WSAPI, () => this.api.sawGetTemplatesT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Reports a click/action event for an engagement (when user interacts with engagement content).
-   * Use this method to track when users click on or interact with engagement content such as inbox messages, popups.
-   * When using for Inbox cases, you need to use message guid as engagement_uid, and pass 31 as activityType, and pass the action/deeplink that was triggered by the user interaction as action.
-   *
+   * Returns the list of mini-games based on the provided parameters. "Limit" and "offset" indicate the range of items to be fetched.
+   * The maximum number of items per request is limited to 20.
+   * You can leave this params empty and by default it will return list of mini-games ranging from 0 to 20.
+   * The returned list of mini-games history is cached for 30 seconds.
    *
    * **Example**:
    * ```
-   * _smartico.api.reportClickEvent({
-   *      engagement_uid: 'abc123-def456',
-   *      activityType: 31 // Inbox
-   *      action: 'dp:gf_missions'
+   * _smartico.api.getMiniGamesHistory().then((result) => {
+   *      console.log(result);
    * });
    * ```
    *
    * **Visitor mode: not supported**
-   *
-   * @param params - Event parameters
-   * @param params.engagement_uid - Unique identifier for the engagement
-   * @param params.activityType - Type of engagement activity (Popup=30, Inbox=31)
-   * @param params.action - Optional action/deeplink that was triggered by the user interaction
    */
-  reportClickEvent({
-    engagement_uid,
-    activityType,
-    action
+  async getMiniGamesHistory({
+    limit,
+    offset,
+    saw_template_id
   }) {
-    this.api.reportEngagementAction(this.userExtId, engagement_uid, activityType, action);
+    return OCache.use(onUpdateContextKey.SAWHistory, ECacheContext.WSAPI, () => this.api.getSawWinningHistoryT(this.userExtId, limit, offset, saw_template_id), CACHE_DATA_SEC);
   }
   /**
-   * Returns the activity log for a user within a specified time range.
-   * The response includes both points changes and gems/diamonds changes.
-   * Each log entry contains information about the change amount, balance, and source.
-   * The returned list is cached for 30 seconds.
-   * You can pass the onUpdate callback as a parameter, it will be called every time the activity log is updated and will provide the updated list of activity logs for the last 10 minutes.
+   * Plays the specified by template_id mini-game on behalf of user and returns prize_id or err_code
+   * After playMiniGame is called, you can call getMiniGames to get the list of mini-games.The returned list of mini-games is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call playMiniGame with a new onUpdate callback, the old one will be overwritten by the new one.
+   * The onUpdate callback will be called on available spin count change, if mini-game has increasing jackpot per spin or won prize is spin/jackpot and if max count of the available user spins equals one, also if the spins were issued to the user manually in the BO. Updated templates will be passed to onUpdate callback.
    *
    * **Example**:
    * ```
-   * const startTime = Math.floor(Date.now() / 1000) - 86400 * 30; // 30 days ago
-   * const endTime = Math.floor(Date.now() / 1000); // now
-   *
-   * _smartico.api.getActivityLog({
-   *      startTimeSeconds: startTime,
-   *      endTimeSeconds: endTime,
-   *      from: 0,
-   *      to: 50,
-   *      onUpdate: (data) => console.log('Updated:', data)
-   * }).then((result) => {
+   * _smartico.api.playMiniGame(55).then((result) => {
    *      console.log(result);
    * });
    * ```
    *
    * **Visitor mode: not supported**
-   *
-   * @param params - Activity log parameters
-   * @param params.startTimeSeconds - Start time in seconds (epoch timestamp)
-   * @param params.endTimeSeconds - End time in seconds (epoch timestamp)
-   * @param params.from - Start index of records to return
-   * @param params.to - End index of records to return
-   * @param params.onUpdate - Optional callback function that will be called when the activity log is updated
    */
-  async getActivityLog({
-    startTimeSeconds,
-    endTimeSeconds,
-    from,
-    to,
+  async playMiniGame(template_id, {
     onUpdate
-  }) {
+  } = {}) {
     if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.ActivityLog, onUpdate);
+      this.onUpdateCallback.set(onUpdateContextKey.Saw, onUpdate);
     }
-    return await OCache.use(onUpdateContextKey.ActivityLog, ECacheContext.WSAPI, () => this.api.getActivityLogT(this.userExtId, startTimeSeconds, endTimeSeconds, from, to), CACHE_DATA_SEC);
+    const r = await this.api.sawSpinRequest(this.userExtId, template_id);
+    this.api.doAcknowledgeRequest(this.userExtId, r.request_id);
+    const o = {
+      err_code: r.errCode,
+      err_message: r.errMsg,
+      prize_id: r.saw_prize_id
+    };
+    return o;
+  }
+  /**
+   * Sends the acknowledge request with specific client_request_id from minigame history in order to claim prize
+   * **Example**:
+   * ```
+   * _smartico.api.miniGameWinAcknowledgeRequest('2a189322-31bb-4119-b943-bx7868ff8dc3').then((result) => {
+   *      console.log(result);
+   * });
+   * ```
+   */
+  async miniGameWinAcknowledgeRequest(request_id) {
+    return this.api.doAcknowledgeRequest(this.userExtId, request_id);
+  }
+  /**
+   * Plays the specified by template_id mini-game on behalf of user spin_count times and returns array of the prizes
+   * After playMiniGameBatch is called, you can call getMiniGames to get the list of mini-games. The returned list of mini-games is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call playMiniGameBatch with a new onUpdate callback, the old one will be overwritten by the new one.
+   * The onUpdate callback will be called on available spin count change, if mini-game has increasing jackpot per spin or won prize is spin/jackpot and if max count of the available user spins equals one, also if the spins were issued to the user manually in the BO. Updated templates will be passed to onUpdate callback.
+   *
+   * **Example**:
+   * ```
+   * _smartico.api.playMiniGameBatch(55, 10).then((result) => {
+   *      console.log(result);
+   * });
+   * ```
+   * **Visitor mode: not supported**
+   */
+  async playMiniGameBatch(template_id, spin_count, {
+    onUpdate
+  } = {}) {
+    if (onUpdate) {
+      this.onUpdateCallback.set(onUpdateContextKey.Saw, onUpdate);
+    }
+    const response = await this.api.sawSpinBatchRequest(this.userExtId, template_id, spin_count);
+    const request_ids = response.results.map(result => result.request_id);
+    this.api.doAcknowledgeBatchRequest(this.userExtId, request_ids);
+    const o = response.results.map(result => ({
+      errCode: result.errCode,
+      errMessage: result.errMsg,
+      saw_prize_id: result.saw_prize_id,
+      jackpot_amount: result.jackpot_amount,
+      first_spin_in_period: result.first_spin_in_period
+    }));
+    return o;
+  }
+  async updateOnSpin(data) {
+    const templates = await OCache.use(onUpdateContextKey.Saw, ECacheContext.WSAPI, () => this.api.sawGetTemplatesT(this.userExtId), CACHE_DATA_SEC);
+    const index = templates.findIndex(t => t.id === data.saw_template_id);
+    templates[index].spin_count = data.spin_count;
+    this.updateEntity(onUpdateContextKey.Saw, templates);
+  }
+  async reloadMiniGameTemplate() {
+    const updatedTemplates = await this.api.sawGetTemplatesT(this.userExtId);
+    this.updateEntity(onUpdateContextKey.Saw, updatedTemplates);
+  }
+}
+
+/** @group Avatars */
+class WSAPIAvatars extends WSAPIMiniGames {
+  /**
+   * Returns the list of avatars available in the catalog for the current user.
+   * The response includes both free avatars and earned/purchased ones.
+   * Avatars with `hide_until_achieved = true` and `is_given = false` should be hidden from the user.
+   * The result is cached for 30 seconds.
+   *
+   * **Example**:
+   * ```
+   * _smartico.api.getAvatarsList().then((result) => {
+   *      console.log(result);
+   * });
+   * ```
+   *
+   * **Visitor mode: not supported**
+   */
+  async getAvatarsList() {
+    return OCache.use(onUpdateContextKey.AvatarsList, ECacheContext.WSAPI, () => this.api.avatarsGetListT(this.userExtId), CACHE_DATA_SEC);
+  }
+  /**
+   * Returns the list of AI-customized avatars for the current user.
+   * Each entry represents a previously generated AI customization for a specific base avatar.
+   * The result is cached for 30 seconds.
+   *
+   * **Example**:
+   * ```
+   * _smartico.api.getAvatarsCustomized().then((result) => {
+   *      console.log(result);
+   * });
+   * ```
+   *
+   * **Visitor mode: not supported**
+   */
+  async getAvatarsCustomized() {
+    return OCache.use(onUpdateContextKey.AvatarsCustomized, ECacheContext.WSAPI, () => this.api.avatarsGetCustomizedT(this.userExtId), CACHE_DATA_SEC);
+  }
+  /**
+   * Returns the list of AI customization prompts (styles) available for avatar customization.
+   * Each prompt represents a visual style that can be applied to a base avatar.
+   * The result is cached for 30 seconds.
+   *
+   * **Example**:
+   * ```
+   * _smartico.api.getAvatarPrompts().then((result) => {
+   *      console.log(result);
+   * });
+   * ```
+   *
+   * **Visitor mode: not supported**
+   */
+  async getAvatarPrompts() {
+    return OCache.use(onUpdateContextKey.AvatarPrompts, ECacheContext.WSAPI, () => this.api.avatarsGetPromptsT(this.userExtId), CACHE_DATA_SEC);
+  }
+  /**
+   * Sets the specified avatar as the active avatar for the current user.
+   * Pass `avatar_url` (the `TAvatarDefinition.url` path or a CDN URL for AI-customized avatars)
+   * and `avatar_real_id` from the avatar catalog.
+   * After a successful call, the avatar list cache is cleared so the next `getAvatarsList()` call reflects `is_in_use`.
+   *
+   * **Example**:
+   * ```
+   * _smartico.api.getAvatarsList().then((avatars) => {
+   *      const avatar = avatars.find((a) => !a.hide_until_achieved || a.is_given);
+   *      if (avatar) {
+   *          _smartico.api.setAvatar({
+   *              avatar_url: avatar.url,
+   *              avatar_real_id: avatar.avatar_real_id,
+   *          }).then((result) => {
+   *              console.log(result);
+   *          });
+   *      }
+   * });
+   * ```
+   *
+   * **Visitor mode: not supported**
+   */
+  async setAvatar(props) {
+    var _r$errCode;
+    if (!props.avatar_url) {
+      throw new Error('avatar_url is required');
+    }
+    if (!props.avatar_real_id) {
+      throw new Error('avatar_real_id is required');
+    }
+    const r = await this.api.avatarSetAvatar(this.userExtId, props.avatar_url, props.avatar_real_id);
+    OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.AvatarsList);
+    OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.AvatarsCustomized);
+    return {
+      err_code: (_r$errCode = r.errCode) != null ? _r$errCode : 0,
+      err_message: r.errMsg
+    };
   }
+}
+
+/** @group GamePick */
+class WSAPIGamePick extends WSAPIAvatars {
   /**
    * Returns the active rounds for the specified MatchX or Quiz game.
    * Each round includes its events (matches/questions) along with the current user's selections and scores.
@@ -3547,466 +5938,274 @@ class WSAPI {
     }
     return this.api.gpGetRoundInfoForUser(props.saw_template_id, props.round_id, props.int_user_id);
   }
+}
+
+/** @group LeaderBoard */
+class WSAPILeaderBoard extends WSAPIGamePick {
   /**
-   * Returns the list of avatars available in the catalog for the current user.
-   * The response includes both free avatars and earned/purchased ones.
-   * Avatars with `hide_until_achieved = true` and `is_given = false` should be hidden from the user.
-   * The result is cached for 30 seconds.
+   * 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.
+   * For example, if the type is Weekly and getPreviousPeriod is true, a leaderboard for the previous week will be returned.
    *
    * **Example**:
    * ```
-   * _smartico.api.getAvatarsList().then((result) => {
-   *      console.log(result);
+   * _smartico.api.getLeaderBoard(1).then((result) => {
+   *     console.log(result);
    * });
    * ```
    *
-   * **Visitor mode: not supported**
-   */
-  async getAvatarsList() {
-    return OCache.use(onUpdateContextKey.AvatarsList, ECacheContext.WSAPI, () => this.api.avatarsGetListT(this.userExtId), CACHE_DATA_SEC);
-  }
-  /**
-   * Returns the list of AI-customized avatars for the current user.
-   * Each entry represents a previously generated AI customization for a specific base avatar.
-   * The result is cached for 30 seconds.
-   *
-   * **Example**:
+   * **Example in the Visitor mode**:
    * ```
-   * _smartico.api.getAvatarsCustomized().then((result) => {
-   *      console.log(result);
+   * _smartico.vapi('EN').getLeaderBoard(1).then((result) => {
+   *    console.log(result);
    * });
    * ```
-   *
-   * **Visitor mode: not supported**
    */
-  async getAvatarsCustomized() {
-    return OCache.use(onUpdateContextKey.AvatarsCustomized, ECacheContext.WSAPI, () => this.api.avatarsGetCustomizedT(this.userExtId), CACHE_DATA_SEC);
+  async getLeaderBoard(periodType, getPreviousPeriod) {
+    return OCache.use(onUpdateContextKey.LeaderBoards, ECacheContext.WSAPI, () => this.api.leaderboardsGetT(this.userExtId, periodType, getPreviousPeriod), CACHE_DATA_SEC);
   }
+}
+
+/** @group Inbox */
+class WSAPIInbox extends WSAPILeaderBoard {
   /**
-   * Returns the list of AI customization prompts (styles) available for avatar customization.
-   * Each prompt represents a visual style that can be applied to a base avatar.
-   * The result is cached for 30 seconds.
+   * Reports an impression event for an engagement (when engagement content is displayed to the user).
+   * Use this method to track when users view engagement content such as inbox messages, popups.
+   * When using for Inbox cases, you need to use message guid as engagement_uid, and pass 31 as activityType.
    *
    * **Example**:
    * ```
-   * _smartico.api.getAvatarPrompts().then((result) => {
-   *      console.log(result);
+   * _smartico.api.reportImpressionEvent({
+   *      engagement_uid: 'abc123-def456',
+   *      activityType: 31 // Inbox
    * });
    * ```
    *
    * **Visitor mode: not supported**
+   *
+   * @param params - Event parameters
+   * @param params.engagement_uid - Unique identifier for the engagement
+   * @param params.activityType - Type of engagement activity (Popup=30, Inbox=31)
    */
-  async getAvatarPrompts() {
-    return OCache.use(onUpdateContextKey.AvatarPrompts, ECacheContext.WSAPI, () => this.api.avatarsGetPromptsT(this.userExtId), CACHE_DATA_SEC);
+  reportImpressionEvent({
+    engagement_uid,
+    activityType
+  }) {
+    this.api.reportEngagementImpression(this.userExtId, engagement_uid, activityType);
   }
   /**
-   * Sets the specified avatar as the active avatar for the current user.
-   * Pass `avatar_url` (the `TAvatarDefinition.url` path or a CDN URL for AI-customized avatars)
-   * and `avatar_real_id` from the avatar catalog.
-   * After a successful call, the avatar list cache is cleared so the next `getAvatarsList()` call reflects `is_in_use`.
+   * Reports a click/action event for an engagement (when user interacts with engagement content).
+   * Use this method to track when users click on or interact with engagement content such as inbox messages, popups.
+   * When using for Inbox cases, you need to use message guid as engagement_uid, and pass 31 as activityType, and pass the action/deeplink that was triggered by the user interaction as action.
    *
    * **Example**:
    * ```
-   * _smartico.api.getAvatarsList().then((avatars) => {
-   *      const avatar = avatars.find((a) => !a.hide_until_achieved || a.is_given);
-   *      if (avatar) {
-   *          _smartico.api.setAvatar({
-   *              avatar_url: avatar.url,
-   *              avatar_real_id: avatar.avatar_real_id,
-   *          }).then((result) => {
-   *              console.log(result);
-   *          });
-   *      }
+   * _smartico.api.reportClickEvent({
+   *      engagement_uid: 'abc123-def456',
+   *      activityType: 31 // Inbox
+   *      action: 'dp:gf_missions'
    * });
    * ```
    *
    * **Visitor mode: not supported**
+   *
+   * @param params - Event parameters
+   * @param params.engagement_uid - Unique identifier for the engagement
+   * @param params.activityType - Type of engagement activity (Popup=30, Inbox=31)
+   * @param params.action - Optional action/deeplink that was triggered by the user interaction
    */
-  async setAvatar(props) {
-    var _r$errCode;
-    if (!props.avatar_url) {
-      throw new Error('avatar_url is required');
-    }
-    if (!props.avatar_real_id) {
-      throw new Error('avatar_real_id is required');
-    }
-    const r = await this.api.avatarSetAvatar(this.userExtId, props.avatar_url, props.avatar_real_id);
-    OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.AvatarsList);
-    OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.AvatarsCustomized);
-    return {
-      err_code: (_r$errCode = r.errCode) != null ? _r$errCode : 0,
-      err_message: r.errMsg
-    };
-  }
-  async updateOnSpin(data) {
-    const templates = await OCache.use(onUpdateContextKey.Saw, ECacheContext.WSAPI, () => this.api.sawGetTemplatesT(this.userExtId), CACHE_DATA_SEC);
-    const index = templates.findIndex(t => t.id === data.saw_template_id);
-    templates[index].spin_count = data.spin_count;
-    this.updateEntity(onUpdateContextKey.Saw, templates);
-  }
-  async reloadMiniGameTemplate() {
-    const updatedTemplates = await this.api.sawGetTemplatesT(this.userExtId);
-    this.updateEntity(onUpdateContextKey.Saw, updatedTemplates);
-  }
-  async updateMissions() {
-    const payload = await this.api.missionsGetItemsT(this.userExtId);
-    this.updateEntity(onUpdateContextKey.Missions, payload);
-  }
-  async updateBonuses() {
-    const payload = await this.api.bonusesGetItemsT(this.userExtId);
-    this.updateEntity(onUpdateContextKey.Bonuses, payload);
-  }
-  async updateTournaments() {
-    const payload = await this.api.tournamentsGetLobbyT(this.userExtId);
-    this.updateEntity(onUpdateContextKey.TournamentList, payload);
-  }
-  async updateClans() {
-    const payload = await this.api.clansGetListT(this.userExtId);
-    this.updateEntity(onUpdateContextKey.Clans, payload);
-  }
-  async updateStorePurchasedItems() {
-    const payload = await this.api.storeGetPurchasedItemsT(this.userExtId, 20, 0);
-    this.updateEntity(onUpdateContextKey.StoreHistory, payload);
-  }
-  async updateStoreItems() {
-    const payload = await this.api.storeGetItemsT(this.userExtId);
-    this.updateEntity(onUpdateContextKey.StoreItems, payload);
-  }
-  async updateInboxUnreadCount(count) {
-    this.updateEntity(onUpdateContextKey.InboxUnreadCount, count);
-  }
-  async updateInboxMessages() {
-    const payload = await this.api.getInboxMessagesT(this.userExtId);
-    this.updateEntity(onUpdateContextKey.InboxMessages, payload);
-  }
-  async updateRaffles() {
-    const payload = await this.api.getRafflesT(this.userExtId);
-    this.updateEntity(onUpdateContextKey.Raffles, payload);
-  }
-  async notifyActivityLogUpdate() {
-    const startSeconds = Date.now() / 1000 - 600;
-    const endSeconds = Date.now() / 1000;
-    const payload = await this.api.getActivityLogT(this.userExtId, startSeconds, endSeconds, 0, 50);
-    this.updateEntity(onUpdateContextKey.ActivityLog, payload);
-  }
-  async updateEntity(contextKey, payload) {
-    OCache.set(contextKey, payload, ECacheContext.WSAPI);
-    const onUpdate = this.onUpdateCallback.get(contextKey);
-    if (onUpdate) {
-      onUpdate(payload);
-    }
-  }
-  async jackpotClearCache() {
-    OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.Jackpots);
-    OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.Pots);
-    OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.JackpotWinners);
-  }
-  /** Returns list of Jackpots that are active in the system and matching to the filter definition.
-   * If filter is not provided, all active jackpots will be returned.
-   * Filter can be used to get jackpots related to specific game or specific jackpot template.
-   * 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
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.jackpotGet({ related_game_id: 'wooko-slot' }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').jackpotGet({ related_game_id: 'wooko-slot' }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   */
-  async jackpotGet(filter) {
-    var _this = this;
-    const signature = `${filter == null ? void 0 : filter.jp_template_id}:${filter == null ? void 0 : filter.related_game_id}`;
-    if (signature !== this.jackpotGetSignature) {
-      this.jackpotGetSignature = signature;
-      this.jackpotClearCache();
-    }
-    let jackpots = [];
-    let pots = [];
-    jackpots = await OCache.use(onUpdateContextKey.Jackpots, ECacheContext.WSAPI, async function () {
-      const _jackpots = await _this.api.jackpotGet(_this.userExtId, filter);
-      const _pots = _jackpots.items.map(jp => jp.pot);
-      _jackpots.items.forEach(jp => {
-        jp.jp_public_meta.custom_data = IntUtils.JsonOrText(jp.jp_public_meta.custom_data);
-      });
-      OCache.set(onUpdateContextKey.Pots, _pots, ECacheContext.WSAPI, JACKPOT_POT_CACHE_SEC);
-      return _jackpots.items;
-    }, JACKPOT_TEMPLATE_CACHE_SEC);
-    if (jackpots.length > 0) {
-      pots = await OCache.use(onUpdateContextKey.Pots, ECacheContext.WSAPI, async function () {
-        const jp_template_ids = jackpots.map(jp => jp.jp_template_id);
-        return (await _this.api.potGet(_this.userExtId, {
-          jp_template_ids
-        })).items;
-      }, JACKPOT_POT_CACHE_SEC);
-    }
-    return jackpots.map(jp => {
-      let _jp = _extends({}, jp, {
-        pot: pots.find(p => p.jp_template_id === jp.jp_template_id)
-      });
-      return _jp;
-    });
-  }
-  /**
-   * Opt-in currently logged in user to the jackpot with the specified jp_template_id.
-   * You may call jackpotGet method after doing optin to see that user is opted in to the jackpot.
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.jackpotOptIn({ jp_template_id: 123 }).then((result) => {
-   *      console.log('Opted in to the jackpot');
-   * });
-   * ```
-   *
-   * **Visitor mode: not supported**
-   *
-   */
-  async jackpotOptIn(filter) {
-    if (!filter.jp_template_id) {
-      throw new Error('jp_template_id is required in jackpotOptIn');
-    }
-    const result = await this.api.jackpotOptIn(this.userExtId, filter);
-    return result;
+  reportClickEvent({
+    engagement_uid,
+    activityType,
+    action
+  }) {
+    this.api.reportEngagementAction(this.userExtId, engagement_uid, activityType, action);
   }
-  /**
-   * Opt-out currently logged in user from the jackpot with the specified jp_template_id.
-   * You may call jackpotGet method after doing optout to see that user is not opted in to the jackpot.
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.jackpotOptOut({ jp_template_id: 123 }).then((result) => {
-   *      console.log('Opted out from the jackpot');
-   * });
-   * ```
+  /** Returns inbox messages based on the provided parameters. "From" and "to" indicate the range of messages to be fetched.
+   * The maximum number of messages per request is limited to 20.
+   * An indicator "onlyFavorite" can be passed to get only messages marked as favorites.
+   * An indicator "read_status" can be passed to get only messages marked as read or unread.
+   * You can leave this params empty and by default it will return list of messages ranging from 0 to 20.
+   * This function returns a list of messages without the body of each message.
+   * To get the body of the message you need to call getInboxMessageBody function and pass the message guid contained in each message of this request.
+   * All other action like mark as read, favorite, delete, etc. can be done using this message GUID.
+   * The "onUpdate" callback will be triggered when the user receives a new message. It will provide an updated list of messages, ranging from 0 to 20, to the onUpdate callback function.
    *
    * **Visitor mode: not supported**
    *
+   * @param params
    */
-  async jackpotOptOut(filter) {
-    if (!filter.jp_template_id) {
-      throw new Error('jp_template_id is required in jackpotOptOut');
+  async getInboxMessages({
+    from,
+    to,
+    onlyFavorite,
+    categoryId,
+    read_status,
+    onUpdate
+  } = {}) {
+    if (onUpdate) {
+      this.onUpdateCallback.set(onUpdateContextKey.InboxMessages, onUpdate);
     }
-    const result = await this.api.jackpotOptOut(this.userExtId, filter);
-    return result;
-  }
-  /**
-   * Returns jackpot winners for the given `jp_template_id` (paginated on the server).
-   * Default page size on the wire is 20; use `limit`, `offset`, and repeated calls to load more.
-   * The full protocol response also includes `has_more`; this method returns only the `winners` array.
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.getJackpotWinners({
-   *      jp_template_id: 123,
-   * }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *
-   * **Visitor mode: not supported**
-   *
-   * @param params - Jackpot winners parameters
-   * @param params.jp_template_id - Jackpot template id (required; throws if missing)
-   * @param params.limit - Page size (server default 20 when omitted)
-   * @param params.offset - Offset into the winner list
-   */
-  async getJackpotWinners({
-    limit,
-    offset,
-    jp_template_id
-  }) {
-    return OCache.use(onUpdateContextKey.JackpotWinners + jp_template_id, ECacheContext.WSAPI, () => this.api.getJackpotWinnersT(this.userExtId, limit, offset, jp_template_id), JACKPOT_WINNERS_CACHE_SEC);
+    return await this.api.getInboxMessagesT(this.userExtId, from, to, onlyFavorite, categoryId, read_status);
   }
   /**
-   * Returns the eligible games for the jackpot with the specified jp_template_id.
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.getJackpotEligibleGames({ jp_template_id: 123 }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * Returns inbox unread count.
    *
    * **Visitor mode: not supported**
-   *
+   * @param params
    */
-  async getJackpotEligibleGames({
-    jp_template_id,
+  async getInboxUnreadCount({
     onUpdate
-  }) {
+  } = {}) {
     if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.JackpotEligibleGames, onUpdate);
+      this.onUpdateCallback.set(onUpdateContextKey.InboxUnreadCount, onUpdate);
     }
-    return OCache.use(onUpdateContextKey.JackpotEligibleGames + jp_template_id, ECacheContext.WSAPI, () => this.api.getJackpotEligibleGamesT(this.userExtId, {
-      jp_template_id
-    }), JACKPOT_ELIGIBLE_GAMES_CACHE_SEC);
+    return OCache.use(onUpdateContextKey.InboxUnreadCount, ECacheContext.WSAPI, () => this.api.getInboxUnreadCountT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Returns all the related tournaments and missions for the provided game id for the current user
-   * The provided Game ID should correspond to the ID from the Games Catalog - https://help.smartico.ai/welcome/technical-guides/games-catalog-api
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.getRelatedItemsForGame('gold-slot2').then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * Returns the message body of the specified message guid.
    *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getRelatedItemsForGame('gold-slot2').then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * **Visitor mode: not supported**
    */
-  async getRelatedItemsForGame(related_game_id) {
-    const result = await this.api.getRelatedItemsForGame(this.userExtId, related_game_id);
-    return result;
+  async getInboxMessageBody(messageGuid) {
+    return await this.api.getInboxMessageBodyT(messageGuid);
   }
   /**
-   * Returns the list of Raffles available for user
-   * The returned list of Raffles is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call getRaffles with a new onUpdate callback, the old one will be overwritten by the new one.
-   * The onUpdate callback will be called on claiming prize.  Updated Raffles will be passed to onUpdate callback.
-   *
-   * **Example**:
-   *
-   * ```
-   * _smartico.api.getRaffles().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *
-   * **Example in the Visitor mode**:
-   *
-   * ```
-   * _smartico.vapi('EN').getRaffles().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * Requests to mark inbox message with specified guid as read
    *
+   * **Visitor mode: not supported**
    */
-  async getRaffles({
-    onUpdate
-  } = {}) {
-    if (onUpdate) {
-      this.onUpdateCallback.set(onUpdateContextKey.Raffles, onUpdate);
-    }
-    return OCache.use(onUpdateContextKey.Raffles, ECacheContext.WSAPI, () => this.api.getRafflesT(this.userExtId), CACHE_DATA_SEC);
+  async markInboxMessageAsRead(messageGuid) {
+    const r = await this.api.markInboxMessageRead(this.userExtId, messageGuid);
+    return {
+      err_code: r.errCode,
+      err_message: r.errMsg
+    };
   }
   /**
-   * Returns draw run for provided raffle_id and run_id.
-   * You can pass winners_from and winners_to parameters to get a specific range of winners. Default is 0-20.
-   *
-   *
-   * **Example**:
-   *
-   * ```javascript
-   * _smartico.api.getRaffleDrawRun({raffle_id: 156, run_id: 145}).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *
-   * **Example in the Visitor mode**:
-   *
-   *
-   * ```javascript
-   * _smartico.vapi('EN').getRaffleDrawRun({ raffle_id: 156, run_id: 145 }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * Requests to mark all inbox messages as read
    *
+   * **Visitor mode: not supported**
    */
-  async getRaffleDrawRun(props) {
-    if (!props.raffle_id || !props.run_id) {
-      throw new Error('both raffle_id and run_id are required');
-    }
-    return await this.api.getRaffleDrawRunT(this.userExtId, props.raffle_id, props.run_id, props.winners_from, props.winners_to);
+  async markAllInboxMessagesAsRead() {
+    const r = await this.api.markAllInboxMessageRead(this.userExtId);
+    return {
+      err_code: r.errCode,
+      err_message: r.errMsg
+    };
   }
   /**
-   * Returns history of draw runs for the provided raffle_id and draw_id, if the draw_id is not provided will return history of all the draws for the provided raffle_id
-   *
-   *
-   * **Example**:
-   *
-   * ```javascript
-   * _smartico.api.getRaffleDrawRunsHistory({ raffle_id: 156, draw_id: 432 }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *
-   * **Example in the Visitor mode**:
-   *
-   * ```javascript
-   * _smartico.vapi('EN').getRaffleDrawRunsHistory({ raffle_id: 156, draw_id: 432 }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * Requests to mark inbox message with specified guid as favorite. Pass mark true to add message to favorite and false to remove.
    *
+   * **Visitor mode: not supported**
    */
-  async getRaffleDrawRunsHistory(props) {
-    const res = await this.api.getRaffleDrawRunsHistory(this.userExtId, props);
-    if (!props.raffle_id) {
-      throw new Error('raffle_id is required');
-    }
-    return drawRunHistoryTransform(res);
+  async markUnmarkInboxMessageAsFavorite(messageGuid, mark) {
+    const r = await this.api.markUnmarkInboxMessageAsFavorite(this.userExtId, messageGuid, mark);
+    return {
+      err_code: r.errCode,
+      err_message: r.errMsg
+    };
   }
   /**
-   * Returns `err_code` and `err_message` after the call; `err_code` 0 means the request succeeded.
-   *
-   *
-   * **Example**:
-   *
-   * ```javascript
-   * _smartico.api.claimRafflePrize({won_id:251}).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
-   *
-   * **Example in the Visitor mode**:
-   *
-   * ```javascript
-   * _smartico.vapi('EN').claimRafflePrize({ won_id: 251 }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * Requests to delete inbox message
    *
+   * **Visitor mode: not supported**
    */
-  async claimRafflePrize(props) {
-    if (!props.won_id) {
-      throw new Error('won_id is required');
-    }
-    const res = await this.api.claimRafflePrize(this.userExtId, {
-      won_id: props.won_id
-    });
-    return raffleClaimPrizeResponseTransform(res);
+  async deleteInboxMessage(messageGuid) {
+    const r = await this.api.deleteInboxMessage(this.userExtId, messageGuid);
+    return {
+      err_code: r.errCode,
+      err_message: r.errMsg
+    };
   }
   /**
-   * Requests an opt-in for the specified raffle. Returns the err_code.
+   * Requests to delete all inbox messages
    *
    * **Visitor mode: not supported**
    */
-  async requestRaffleOptin(props) {
-    if (!props.raffle_id) {
-      throw new Error('raffle_id is required');
-    }
-    if (!props.draw_id) {
-      throw new Error('draw_id is required');
-    }
-    if (!props.raffle_run_id) {
-      throw new Error('raffle_run_id is required');
-    }
-    const r = await this.api.raffleOptin(this.userExtId, props);
+  async deleteAllInboxMessages() {
+    const r = await this.api.deleteAllInboxMessages(this.userExtId);
     return {
       err_code: r.errCode,
       err_message: r.errMsg
     };
   }
+  async updateInboxUnreadCount(count) {
+    this.updateEntity(onUpdateContextKey.InboxUnreadCount, count);
+  }
+  async updateInboxMessages() {
+    const payload = await this.api.getInboxMessagesT(this.userExtId);
+    this.updateEntity(onUpdateContextKey.InboxMessages, payload);
+  }
+}
+
+/**
+ * Public surface of the Smartico WebSocket API. The consumer reaches every
+ * method on this class via `_smartico.api.X(...)`. The class is the
+ * terminator of an inheritance chain that splits the surface into focused
+ * domain classes (see `WSAPIBase` → `WSAPIUser` → ... → `WSAPIInbox` →
+ * `WSAPI`); each domain class hosts its own subset of methods. Consumers
+ * don't need to know about the chain — every method is reachable directly
+ * on the `WSAPI` instance via prototype-chain lookup.
+ *
+ * @group General API
+ */
+class WSAPI extends WSAPIInbox {
+  /** @private */
+  constructor(api, userExtId = null) {
+    super(api, userExtId);
+    // Push-subscription wiring. This block must live in the terminator
+    // because it references `update*` helpers defined across multiple
+    // domain classes; only the terminator has visibility into all of
+    // them via the prototype chain.
+    if (this.api.tracker) {
+      const on = this.api.tracker.on;
+      on(ClassId.SAW_SPINS_COUNT_PUSH, data => this.updateOnSpin(data));
+      on(ClassId.SAW_SHOW_SPIN_PUSH, () => this.reloadMiniGameTemplate());
+      on(ClassId.SAW_AKNOWLEDGE_RESPONSE, () => {
+        this.reloadMiniGameTemplate();
+        OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
+      });
+      on(ClassId.SAW_DO_SPIN_RESPONSE, () => {
+        this.reloadMiniGameTemplate();
+        OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
+      });
+      on(ClassId.MISSION_OPTIN_RESPONSE, () => this.updateMissions());
+      on(ClassId.ACHIEVEMENT_CLAIM_PRIZE_RESPONSE, () => this.updateMissions());
+      on(ClassId.RELOAD_ACHIEVEMENTS_EVENT, () => this.updateMissions());
+      on(ClassId.TOURNAMENT_REGISTER_RESPONSE, () => this.updateTournaments());
+      on(ClassId.BUY_SHOP_ITEM_RESPONSE, () => {
+        this.updateStorePurchasedItems();
+        this.updateStoreItems();
+      });
+      on(ClassId.CLIENT_ENGAGEMENT_EVENT_NEW, () => this.updateInboxMessages());
+      on(ClassId.LOGOUT_RESPONSE, () => OCache.clearContext(ECacheContext.WSAPI));
+      on(ClassId.IDENTIFY_RESPONSE, () => OCache.clearContext(ECacheContext.WSAPI));
+      on(ClassId.JP_WIN_PUSH, _data => this.jackpotClearCache());
+      on(ClassId.JP_OPTOUT_RESPONSE, _data => this.jackpotClearCache());
+      on(ClassId.JP_OPTIN_RESPONSE, _data => this.jackpotClearCache());
+      on(ClassId.CLAIM_BONUS_RESPONSE, () => this.updateBonuses());
+      on(ClassId.SAW_DO_SPIN_BATCH_RESPONSE, () => {
+        this.reloadMiniGameTemplate();
+        OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
+      });
+      on(ClassId.RAF_CLAIM_PRIZE_RESPONSE, () => this.updateRaffles());
+      on(ClassId.GET_INBOX_MESSAGES_RESPONSE, res => {
+        if (res.unread_count !== undefined && res.unread_count !== null) {
+          this.updateInboxUnreadCount(res.unread_count);
+        }
+      });
+      on(ClassId.CLIENT_PUBLIC_PROPERTIES_CHANGED_EVENT, data => {
+        var _data$props, _data$props2, _data$props3, _data$props4, _data$props5;
+        if ((data == null || (_data$props = data.props) == null ? void 0 : _data$props.core_inbox_unread_count) !== undefined && (data == null || (_data$props2 = data.props) == null ? void 0 : _data$props2.core_inbox_unread_count) !== null) {
+          this.updateInboxUnreadCount(data.props.core_inbox_unread_count);
+        }
+        if ((data == null || (_data$props3 = data.props) == null ? void 0 : _data$props3.ach_points_balance) !== undefined || (data == null || (_data$props4 = data.props) == null ? void 0 : _data$props4.ach_gems_balance) !== undefined || (data == null || (_data$props5 = data.props) == null ? void 0 : _data$props5.ach_diamonds_balance) !== undefined) {
+          this.notifyActivityLogUpdate();
+        }
+      });
+      on(ClassId.RAF_OPTIN_RESPONSE, () => this.updateRaffles());
+    }
+  }
 }
 
 var AchCustomSectionType;