@smartico/public-api 0.0.380 → 0.0.381

package/dist/index.modern.mjs

@@ -153,6 +153,8 @@ var ClassId;
   ClassId[ClassId["RAF_CLAIM_PRIZE_RESPONSE"] = 909] = "RAF_CLAIM_PRIZE_RESPONSE";
   ClassId[ClassId["RAF_OPTIN_REQUEST"] = 916] = "RAF_OPTIN_REQUEST";
   ClassId[ClassId["RAF_OPTIN_RESPONSE"] = 917] = "RAF_OPTIN_RESPONSE";
+  ClassId[ClassId["RAF_GET_WON_PRIZES_REQUEST"] = 920] = "RAF_GET_WON_PRIZES_REQUEST";
+  ClassId[ClassId["RAF_GET_WON_PRIZES_RESPONSE"] = 921] = "RAF_GET_WON_PRIZES_RESPONSE";
   /*
   RAF_GET_TICKETS_REQUEST = 902,
   RAF_GET_TICKETS_RESPONSE = 903,
@@ -2436,7 +2438,7 @@ class WSAPIUser extends WSAPIBase {
    *
    * **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
+   * prefer this field over `getInboxUnreadCount` (which is cached
    * for 30 s) — same value, fresher signal.
    *
    * **Language**: `core_user_language` reflects the server's stored
@@ -2506,15 +2508,75 @@ class WSAPIUser extends WSAPIBase {
       throw new Error('Tracker is not initialized, cannot getUserProfile');
     }
   }
-  /** Check if user belongs to specific segments
-   * **Example**:
-   * ```
-   * _smartico.api.checkSegmentMatch(1).then((result) => {
-   *   console.log(result);
+  /**
+   * Checks whether the current user matches a single segment, returning
+   * `true` / `false` directly. Use this as a decision primitive to gate
+   * UI surfaces (e.g. show a "VIP lounge" tab only when the user is in
+   * the VIP segment), or to drive segment-specific CTA copy.
+   *
+   * Every call is a server round-trip — there is no SDK-side cache. For
+   * checking multiple segments in one round-trip, use
+   * {@link checkSegmentListMatch} instead.
+   *
+   * @remarks
+   * **Refresh model**
+   * - **No client cache.** Every call sends a request; the SDK does not
+   *   memoize results.
+   * - **No push event** notifies the consumer when segment membership
+   *   flips (the user crosses a qualification threshold, or the
+   *   operator changes the segment definition). Membership changes
+   *   become visible only on the next `checkSegmentMatch` call.
+   * - **Behavioral segments (configured against BigQuery) have batch
+   *   lag** — even if the user's activity has changed (deposit, wager,
+   *   etc.), the segment-membership result may not reflect that change
+   *   until the next batch evaluation run (typically up to several
+   *   hours).
+   *
+   * **Rate limit** (important)
+   * The server caps `checkSegment*` calls at **10 requests per
+   * 60-second window**, with a minimum gap of **~5 seconds between
+   * consecutive calls**. Avoid calling on every render — cache the
+   * result client-side for the session, or until you have a reason to
+   * believe the user's state changed (e.g. after a deposit completes,
+   * a level changes via {@link getUserProfile}'s `props_change`, or a
+   * specific custom event fires).
+   *
+   * **`is_matching: false` is ambiguous on the server** — both "the
+   * segment doesn't exist for this label" and "the user doesn't
+   * qualify" return `false` with no distinguishing signal. Pass IDs
+   * you've verified are valid for your label.
+   *
+   * **Idempotency**: safe. Read-only. No side effects (no analytics
+   * events, no DB writes).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param segment_id  The segment ID. Segment IDs are label-scoped;
+   *                    the same numeric ID can refer to different
+   *                    segments under different labels. Use the IDs
+   *                    configured for your label.
+   * @returns           `true` if the user currently matches the
+   *                    segment, `false` otherwise. `false` also covers
+   *                    the "segment doesn't exist for this label"
+   *                    case — these are not distinguishable.
+   *
+   * @example
+   * ```ts
+   * const isVip = await window._smartico.api.checkSegmentMatch(vipSegmentId);
+   * if (isVip) {
+   *   console.log('[smartico] user is in VIP segment — render the VIP-only widget surface');
+   * } else {
+   *   console.log('[smartico] user not in VIP segment (or segment id misconfigured) — hide the VIP surface');
+   * }
+   *
+   * // Cache the result for the session; re-check after material user-state changes.
+   * window._smartico.on('props_change', async (changed) => {
+   *   if ('ach_points_ever' in changed || 'ach_level_current_id' in changed) {
+   *     const fresh = await window._smartico.api.checkSegmentMatch(vipSegmentId);
+   *     console.log('[smartico] user state changed — VIP membership now:', fresh);
+   *   }
    * });
    * ```
-   *
-   * **Visitor mode: not supported**
    */
   async checkSegmentMatch(segment_id) {
     const r = await this.api.coreCheckSegments(this.userExtId, [segment_id]);
@@ -2524,14 +2586,67 @@ class WSAPIUser extends WSAPIBase {
       return false;
     }
   }
-  /** Check if user belongs to specific list of segments
-   * **Example**:
-   * ```
-   * _smartico.api.checkSegmentListMatch([1, 2, 3]).then((result) => {
-   *    console.log(result);
-   * });
+  /**
+   * Checks the current user's membership in multiple segments in a
+   * single server round-trip — returns a `TSegmentCheckResult[]` with
+   * one entry per *unique* segment ID. Use this instead of looping
+   * {@link checkSegmentMatch} when you need to evaluate several
+   * segments at once (e.g. multi-segment composite gating, A/B-style
+   * cohort detection).
+   *
+   * @remarks
+   * **Response order is NOT guaranteed**
+   * The server returns results in an unspecified order — different
+   * from the input array. Always correlate by the `segment_id` field on
+   * each `TSegmentCheckResult` rather than by array position. The
+   * returned array length may also be smaller than the input array
+   * (duplicate IDs are silently de-duplicated server-side).
+   *
+   * **Single round-trip**
+   * The entire `segment_ids` array is sent in one request. Two segments
+   * cost the same as one in terms of network latency and rate-limit
+   * consumption (one call = one rate-limit slot, regardless of how many
+   * segments).
+   *
+   * **Shared semantics with `checkSegmentMatch`**
+   * Both methods wrap the same underlying server endpoint and share
+   * the same caching, refresh, rate-limit, and ambiguity behavior. See
+   * {@link checkSegmentMatch} for: no client cache · no push event for
+   * membership changes · behavioral segments have batch lag · rate
+   * limit (10 requests / 60 s, ~5 s minimum gap between calls) ·
+   * `is_matching: false` doesn't distinguish "not in segment" from
+   * "segment doesn't exist for this label".
+   *
+   * **Idempotency**: safe. Read-only. No side effects.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param segment_ids  Array of segment IDs to check. Duplicates are
+   *                     silently de-duplicated server-side. Segment IDs
+   *                     are label-scoped — use the IDs configured for
+   *                     your label.
+   * @returns            Array of `{ segment_id, is_matching }` results.
+   *                     Order is NOT guaranteed; correlate by
+   *                     `segment_id`. Length may be less than the input
+   *                     when duplicate IDs were sent.
+   *
+   * @example
+   * ```ts
+   * const segmentIds = [vipSegmentId, newPlayerSegmentId, freeRollSegmentId];
+   * const results = await window._smartico.api.checkSegmentListMatch(segmentIds);
+   *
+   * // Always correlate by segment_id — the response order is unspecified.
+   * const byId = new Map(results.map(r => [r.segment_id, r.is_matching]));
+   *
+   * if (byId.get(vipSegmentId)) {
+   *   console.log('[smartico] user is in VIP segment — render VIP surface');
+   * }
+   * if (byId.get(newPlayerSegmentId) && byId.get(freeRollSegmentId)) {
+   *   console.log('[smartico] new player AND eligible for free roll — show the welcome promo');
+   * }
+   *
+   * // Cache the result map for the session; refresh on material state changes.
    * ```
-   * **Visitor mode: not supported**
    */
   async checkSegmentListMatch(segment_ids) {
     return await this.api.coreCheckSegments(this.userExtId, Array.isArray(segment_ids) ? segment_ids : [segment_ids]);
@@ -2689,7 +2804,7 @@ class WSAPIUser extends WSAPIBase {
    * 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
+   * `getTranslations` — the operator's display strings are
    * stored under the translation keys `levelsCounter1Name` and
    * `levelsCounter2Name`.
    *
@@ -2747,36 +2862,68 @@ class WSAPIUser extends WSAPIBase {
     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.
+   * Returns the user's unified balance-change history — every points, gems, and
+   * diamonds transaction within the requested time window, ordered newest-first.
+   * Use to power an "Activity" / "History" tab showing wins, claims, purchases,
+   * level-up rewards, and operator adjustments.
    *
-   * **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) => {
-   *      console.log(result);
-   * });
-   * ```
+   * The returned shape is the same regardless of currency type — `type` (see
+   * {@link UserBalanceType}) distinguishes points / gems / diamonds and
+   * `source_type_id` (see {@link PointChangeSourceType}) names the originating
+   * event.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode is not guarded at the SDK level
+   *   but is not meaningful — activity is per-user.
+   *
+   * **Pagination — `from` / `to` are offset + ceiling, not timestamps**
+   * The SDK derives `offset = from`, `limit = min(to - from, 50)` — the server
+   * hard-caps a single response at 50 entries. For infinite scroll, advance
+   * `from` by 50 between calls. Both `startTimeSeconds` and `endTimeSeconds`
+   * are epoch seconds bounding the window the server scans.
+   *
+   * **Subscription model (`onUpdate`)**
+   * The callback fires when the user's `ach_points_balance`,
+   * `ach_gems_balance`, or `ach_diamonds_balance` changes (i.e. whenever a
+   * wallet event lands). The pushed payload is a FIXED re-fetch of the
+   * **last 10 minutes / first 50 entries** — it does NOT honor the original
+   * call's `startTimeSeconds` / `endTimeSeconds` / `from` / `to`. Consumers
+   * maintaining a long historical view must re-call `getActivityLog` with
+   * their own params after receiving an `onUpdate` notification.
+   *
+   * **Refresh**
+   * - The SDK caches results for 30 seconds.
+   * - Push triggers fire only on balance changes; transactions that don't
+   *   alter a balance (theoretical zero-amount entries) won't refresh.
+   *
+   * **Visitor mode**: not meaningful (no per-user history available).
+   *
+   * **UI guidance**: see [UI Guide — `getActivityLog`](../../docs/ui/user/UIGuide_getActivityLog.md).
    *
-   * @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
+   * @returns Array of {@link TActivityLog} ordered newest-first.
+   *
+   * @example
+   * ```ts
+   * const now = Math.floor(Date.now() / 1000);
+   * const start = now - 86400 * 30; // 30 days
+   *
+   * const log = await window._smartico.api.getActivityLog({
+   *     startTimeSeconds: start,
+   *     endTimeSeconds:   now,
+   *     from: 0,
+   *     to:   50,
+   *     onUpdate: (refreshed) => {
+   *         console.log('[smartico] wallet changed — refreshed payload is last 10 min / 50 entries:', refreshed.length, 'rows');
+   *         // If the consumer is showing a full 30-day view, re-call getActivityLog with the original params here.
+   *     },
+   * });
+   *
+   * for (const row of log) {
+   *     const sign = row.amount >= 0 ? '+' : '';
+   *     console.log('[smartico] activity row — render with', row.type === 0 ? 'points' : row.type === 1 ? 'gems' : 'diamonds', 'icon, color by sign:', sign + row.amount, 'balance after:', row.balance, 'source:', row.source_type_id);
+   * }
+   * ```
    */
   async getActivityLog({
     startTimeSeconds,
@@ -2800,11 +2947,114 @@ class WSAPIUser extends WSAPIBase {
 
 /** @group General */
 class WSAPIGeneral extends WSAPIUser {
+  /**
+   * Returns the operator-configured "custom sections" the current user is eligible
+   * to see. Custom sections are nav-level entries the operator builds in the BO —
+   * HTML pages, themed mission grids, store / raffle / tournament category pages,
+   * lootbox calendars, redirect links, and Liquid-templated dashboards — each
+   * surfaced with its own icon and label.
+   *
+   * Use the response to build the side menu / bottom-bar / nav grid of a
+   * gamification widget. Each section's `section_type_id` (see
+   * {@link AchCustomSectionType}) tells the consumer which page component to mount
+   * when the user opens the section.
+   *
+   * @remarks
+   * **Preconditions**
+   * - No prerequisite calls. Typically fetched once at app boot to build the
+   *   navigation skeleton.
+   *
+   * **Server-side eligibility filtering**
+   * Sections are filtered server-side by the user's segments / level / brand and
+   * the section's `active_from_date` / `active_till_date` window. Sections the
+   * user is ineligible for are omitted from the response entirely — there is no
+   * "locked" state to render.
+   *
+   * **Ordering**
+   * Response is server-ordered. Render in the order received; do NOT re-sort
+   * client-side (the operator's order is the intended nav order).
+   *
+   * **Refresh**
+   * - The SDK caches results for 30 seconds.
+   * - No push subscription. Re-call after a segment / level change might
+   *   make new sections eligible, or just rely on the 30 s cache turnover.
+   *
+   * **Visitor mode**: supported.
+   *
+   * **UI guidance**: see [UI Guide — `getCustomSections`](../../docs/ui/general/UIGuide_getCustomSections.md).
+   *
+   * @returns Array of {@link TUICustomSection} — empty if the label has no
+   * active custom sections or the user is ineligible for all of them.
+   *
+   * @example
+   * ```ts
+   * const sections = await window._smartico.api.getCustomSections();
+   *
+   * for (const s of sections) {
+   *     console.log('[smartico] nav entry', s.menu_name, 'type', s.section_type_id, '→ mount the matching page component');
+   *     // Render s.menu_img (64x64) as the nav icon and s.menu_name as the label.
+   *     // For section_type_id === AchCustomSectionType.REDIRECT_LINK, do NOT mount a page —
+   *     // resolve s.url_or_dp on click (DP string or external URL).
+   * }
+   * ```
+   */
   async getCustomSections() {
     return OCache.use(onUpdateContextKey.CustomSections, ECacheContext.WSAPI, () => this.api.customSectionsGetT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Requests translations for the given language. Returns the object including translation key/translation value pairs. All possible translation keys defined in the back office.
+   * Returns the full set of operator-defined translation key/value pairs for the
+   * label, merged across the requested language and the English baseline.
+   *
+   * Translation keys are free-form strings defined by the operator in the BO. The
+   * SDK consumer treats the result as a flat dictionary: `translations[key]`. If
+   * the key is missing entirely, do NOT trust `undefined` semantics — defensively
+   * fall back to the key string itself or a hardcoded literal.
+   *
+   * @remarks
+   * **Preconditions**
+   * - No prerequisite calls.
+   * - `lang_code` is the ISO language code the operator uses in the BO
+   *   (e.g. `"EN"`, `"FR"`, `"ES"`). Case is not normalised — match what the
+   *   operator configured.
+   *
+   * **EN fallback**
+   * The SDK issues an English-baseline fetch first, then overlays the
+   * `lang_code` translations on top. Any key the operator has only defined in
+   * English (i.e. missing in the requested language) is returned with the
+   * English value. Keys missing in both are absent from the map — the consumer
+   * must handle missing keys (the default Smartico UI returns the key string
+   * itself as the fallback text).
+   *
+   * **What's included**
+   * The SDK passes an empty `areas` filter to the server, which returns ALL
+   * translation namespaces configured for the label (Gamification, Casino,
+   * Trading, Affiliation, etc. — whichever are populated). For a Gamification-
+   * only widget, the consumer can ignore unused namespaces — keys are flat
+   * strings, not nested.
+   *
+   * **Refresh**
+   * - Cached internally per `(lang_code, label, brand)` for ~30 seconds.
+   * - No push subscription. Operators editing translations in the BO will see
+   *   the change after the cache window expires.
+   *
+   * **Visitor mode**: supported. Translations are label-scoped, not user-
+   * scoped — `lang_code` is the sole language selector and is independent of
+   * the `vapi(lang)` argument used elsewhere.
+   *
+   * @param lang_code  ISO language code (e.g. `"EN"`, `"FR"`). Defaults to
+   *                   `"EN"` server-side if empty.
+   * @returns {@link TGetTranslations} — `{ translations: { [key]: string } }`.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.getTranslations('FR');
+   *
+   * // Defensive lookup: fall back to the key itself if the operator hasn't
+   * // defined the string.
+   * const t = (k: string) => r.translations[k] ?? k;
+   *
+   * console.log('[smartico] localized label "missions_title" →', t('missions_title'));
+   * ```
    */
   async getTranslations(lang_code) {
     const r = await this.api.getTranslationsT(this.userExtId, lang_code, []);
@@ -2813,21 +3063,60 @@ class WSAPIGeneral extends WSAPIUser {
     };
   }
   /**
-   * 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
+   * Returns the missions and tournaments associated with a casino / sportsbook
+   * game in the operator's games catalog — the reverse of "given this mission,
+   * which games count for it" — so you can surface "play this game to progress
+   * mission X" / "tournament Y features this game" badges on game tiles or
+   * detail screens.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.getRelatedItemsForGame('gold-slot2').then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * The shape mirrors `getMissions` (`UserAchievement[]`) and `getTournamentsList`
+   * (`Tournament[]`) — same wire types, no reduced subset.
    *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getRelatedItemsForGame('gold-slot2').then((result) => {
-   *      console.log(result);
-   * });
+   * @remarks
+   * **Preconditions**
+   * - `related_game_id` must be a Games Catalog ID (the same external string the
+   *   operator uses in the catalog at
+   *   {@link https://help.smartico.ai/welcome/technical-guides/games-catalog-api}).
+   *
+   * **Server-side eligibility filtering**
+   * Missions and tournaments are filtered by the user's segments / level / brand
+   * before being returned. A user who is ineligible for a mission segment will
+   * NOT see that mission in the result even if it lists the game. The same
+   * filtering applies to tournaments. Treat the response as "what this user
+   * should see" — no client-side eligibility pass needed.
+   *
+   * **No cache**
+   * Every call is a live server round-trip. Missions/tournaments are operator-
+   * mutated state (opt-in, completion, expiry) that changes during a session;
+   * caching staler than the user's last action would mis-render eligibility.
+   * Avoid building a consumer-side cache for UI-critical paths.
+   *
+   * **Refresh**
+   * - Re-call when the user navigates to a new game tile / detail surface.
+   * - Re-call after the user opts into / completes a related mission to refresh
+   *   the "play this game" badge.
+   *
+   * **Visitor mode**: supported via `_smartico.vapi(lang).getRelatedItemsForGame(...)`.
+   *
+   * **UI guidance**: see [UI Guide — `getRelatedItemsForGame`](../../docs/ui/general/UIGuide_getRelatedItemsForGame.md).
+   *
+   * @param related_game_id  External Games Catalog ID of the game (e.g. `"gold-slot2"`).
+   * @returns {@link GetRelatedAchTourResponse} — `{ achievements, tournaments? }`.
+   * `tournaments` may be `undefined` (treat as empty); both arrays may be empty
+   * when no eligible entities reference the game.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.getRelatedItemsForGame('gold-slot2');
+   *
+   * const missions = r.achievements ?? [];
+   * const tournaments = r.tournaments ?? [];
+   *
+   * if (missions.length === 0 && tournaments.length === 0) {
+   *     console.log('[smartico] no related missions / tournaments — hide the related badge on the game tile');
+   * } else {
+   *     console.log('[smartico] related entities:', missions.length, 'missions /', tournaments.length, 'tournaments — show a "X missions / Y tournaments" badge');
+   * }
    * ```
    */
   async getRelatedItemsForGame(related_game_id) {
@@ -3381,12 +3670,125 @@ class WSAPIMissions extends WSAPIGeneral {
 /** @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.
-   * Note that each time you call getBonuses with a new onUpdate callback, the old one will be overwritten by the new one.
-   * The onUpdate callback will be called on bonus claimed and the updated bonuses will be passed to it.
+   * Returns the bonuses awarded to the current user — both pending
+   * (player-claim required) and already-redeemed. Each bonus carries
+   * a `bonus_status_id` ({@link BonusStatus}) describing its lifecycle
+   * stage and an `is_redeemable` flag that signals whether the
+   * consumer must trigger a manual {@link claimBonus} call.
+   *
+   * Bonuses originate from many sources (CRM rules, mission/tournament
+   * rewards, store redemptions, mini-game prizes, manual operator
+   * awards) and all surface through this single list. The consumer
+   * cannot distinguish the source server-side without operator
+   * coordination.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Subscription model (`onUpdate`)**
+   * The callback receives the FULL refreshed bonuses list (never a
+   * diff/patch). Each subsequent call to `getBonuses({ 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** — the callback fires after every
+   * {@link claimBonus} call resolves on this connection (success OR
+   * failure). This is the ONLY trigger.
+   *
+   * Does NOT fire when: a new bonus is awarded server-side
+   * (CRM rule, mission completion, store purchase, etc.), a bonus
+   * expires, or an operator manually issues / cancels a bonus. Those
+   * changes surface only on the next cache miss (after the 30 s TTL).
+   * Re-call `getBonuses()` manually if your UI needs near-live state
+   * for server-driven awards.
+   *
+   * **Reading state from the returned bonus**
+   * Drive UI bucketing from `bonus_status_id` (enum {@link BonusStatus}):
+   *
+   * - `COUPON_ISSUED` (2) — actionable; player must claim. Pair with
+   *   `is_redeemable === true` to gate the Claim button.
+   * - `REDEEM_FAILED` (4) — also actionable; the previous claim
+   *   attempt failed but the bonus is still valid. Surface a retry CTA
+   *   — the default Smartico UI treats this identically to
+   *   `COUPON_ISSUED` from the player's perspective.
+   * - `REDEEMED` (3) — historical; show in a "claimed" tab.
+   * - `New` (1), `COUPON_ISSUE_FAILED` (5), `EXPIRED` (6) — these
+   *   should not normally reach the client and are typically filtered
+   *   out by operator-side widget configuration; if they do appear,
+   *   they have no player-actionable state.
+   *
+   * `is_redeemable` is the authoritative gate for showing the Claim
+   * button — it's `true` only when the bonus is in a claimable status
+   * AND the operator's integration uses a coupon model (where the
+   * player must explicitly trigger delivery). Auto-redeemed bonuses
+   * arrive already in `REDEEMED` state with `is_redeemable: false`.
+   *
+   * **Field hierarchy — display amount**
+   * Bonuses carry both template-level (`label_bonus_template_meta_map.description`)
+   * and instance-level (`bonus_meta_map.uiAmount`) display strings.
+   * Prefer `bonus_meta_map.uiAmount` when present — it's the dynamic
+   * amount computed at issuance time (e.g. from a dynamic-bonus
+   * formula). Fall back to `label_bonus_template_meta_map.description`
+   * (which can include HTML; sanitize before injecting).
+   *
+   * **Date format**
+   * `create_date` and `redeem_date` are ISO 8601 UTC strings WITHOUT
+   * a timezone suffix (`"YYYY-MM-DDTHH:MM:SS"`). Parse as UTC and
+   * display in the user's local timezone. `redeem_date` is absent
+   * until the bonus reaches `REDEEMED` status.
+   *
+   * **Cache TTL**: the SDK caches the response for 30 seconds. Cache
+   * is fully cleared on login / logout.
+   *
+   * **Idempotency / Side effects**: safe. Read-only.
+   *
+   * **UI guidance**: see [UI Guide — `getBonuses`](../../docs/ui/bonuses/UIGuide_getBonuses.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param params              Optional. Omit to fetch without subscribing.
+   * @param params.onUpdate     Callback invoked with the full refreshed
+   *                            bonuses list after every
+   *                            {@link claimBonus} resolves. Each call
+   *                            to `getBonuses` overwrites the prior
+   *                            callback.
+   * @returns                   Promise resolving to the bonuses list.
+   *                            Empty array if no bonuses are visible.
+   *
+   * @example
+   * ```ts
+   * const bonuses = await window._smartico.api.getBonuses({
+   *   onUpdate: (refreshed) => {
+   *     console.log('[smartico] bonuses refreshed (after claimBonus) — re-render the bonuses UI from this array:', refreshed);
+   *   },
+   * });
+   *
+   * // Bucket into pending vs redeemed tabs. The default Smartico UI groups
+   * // COUPON_ISSUED + REDEEM_FAILED into the same "Pending" tab.
+   * const pending = bonuses.filter(b =>
+   *   b.bonus_status_id === 2 || b.bonus_status_id === 4  // COUPON_ISSUED or REDEEM_FAILED
+   * );
+   * const redeemed = bonuses.filter(b => b.bonus_status_id === 3);  // REDEEMED
+   *
+   * console.log('[smartico] render bonus tabs: pending=', pending.length, 'redeemed=', redeemed.length);
+   *
+   * // Render each pending bonus card; show Claim button only when redeemable.
+   * for (const b of pending) {
+   *   const amount = b.bonus_meta_map?.uiAmount || b.label_bonus_template_meta_map?.description;
+   *   if (b.is_redeemable) {
+   *     console.log('[smartico] render Claim button for bonus', b.bonus_id, '— amount:', amount);
+   *   } else {
+   *     console.log('[smartico] render bonus as informational (no Claim button) — amount:', amount);
+   *   }
+   * }
+   *
+   * // Server-awarded bonuses (e.g. from a CRM campaign) do NOT push;
+   * // poll if you need near-live awareness.
+   * setInterval(async () => {
+   *   const fresh = await window._smartico.api.getBonuses();
+   *   const newCount = fresh.filter(b => b.bonus_status_id === 2 || b.bonus_status_id === 4).length;
+   *   console.log('[smartico] poll tick — pending bonuses now:', newCount);
+   * }, 30_000);
+   * ```
    */
   async getBonuses({
     onUpdate
@@ -3397,12 +3799,113 @@ class WSAPIBonuses extends WSAPIMissions {
     return OCache.use(onUpdateContextKey.Bonuses, ECacheContext.WSAPI, () => this.api.bonusesGetItemsT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Claim the bonus by bonus_id. Returns the err_code in case of success or error.
-   * Note that this method can be used only on integrations where originally failed bonus can be claimed again.
-   * For example, user won a bonus in the mini-game, but Operator rejected this bonus.
-   * This bonus will be available for the user to claim again.
+   * Triggers manual redemption of a coupon-model bonus the user has
+   * been awarded. For bonuses with `is_redeemable === true` returned
+   * by {@link getBonuses}, this is the call that asks the operator's
+   * integration to actually credit the bonus to the player's account.
+   * Bonuses on integrations that auto-redeem arrive already in
+   * `REDEEMED` state and do not require this call.
    *
-   * **Visitor mode: not supported**
+   * Use this for `bonus_status_id` of `COUPON_ISSUED` (2) as the
+   * first-time claim, and for `REDEEM_FAILED` (4) as a retry after a
+   * prior unsuccessful attempt.
+   *
+   * @remarks
+   * **Preconditions**
+   * Read the candidate bonus from {@link getBonuses} and gate the
+   * call on `is_redeemable === true`. The SDK forwards the request
+   * unconditionally — calling on a non-claimable bonus returns
+   * `err_code = -1`.
+   *
+   * **Error codes** (in `err_code`)
+   *
+   * The SDK currently types `err_code` as {@link SAWSpinErrorCode} for
+   * historical reasons, but the values returned by this method come
+   * from the server's general error space and are NOT mini-game codes.
+   * Branch on the numeric values:
+   *
+   * - `0` — success; the bonus has been redeemed and the operator's
+   *   integration has credited the player's account.
+   * - `-1` — bonus not claimable: not found, already claimed by
+   *   another session, or its status is no longer `COUPON_ISSUED` /
+   *   `REDEEM_FAILED`. Treat as idempotent — refresh
+   *   {@link getBonuses} and reconcile.
+   * - `1` — generic server error. Transient; allow retry after a brief
+   *   delay.
+   * - `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.
+   *
+   * **`success` field is unreliable**: the wire response does not
+   * carry a `success` boolean — the field on `TClaimBonusResult` will
+   * be `undefined` in practice. Always branch on `err_code === 0`
+   * for the success check.
+   *
+   * **Refresh after success (and after failure)**
+   * The SDK automatically refreshes the bonuses cache on every
+   * response (success OR failure) and fires any `onUpdate` callback
+   * registered via {@link getBonuses}'s `onUpdate`. After
+   * `err_code === 0`, the redeemed bonus shifts from
+   * `COUPON_ISSUED` / `REDEEM_FAILED` to `REDEEMED` on the refreshed
+   * array, with `redeem_date` populated. After a failure, the bonus
+   * typically lands in `REDEEM_FAILED` and remains claimable for a
+   * retry.
+   *
+   * **Idempotency**: NOT idempotent at the SDK level. A second call
+   * returns `err_code = -1` once the first has succeeded — treat that
+   * as success in the UI rather than as a real error. Guard the call
+   * site against double-clicks (set a local "claiming" flag on click,
+   * clear it on response).
+   *
+   * **Side effects** (on `err_code === 0`)
+   * - Bonus status transitions to `REDEEMED`; `redeem_date` is set.
+   * - The operator's integration credits the player's account
+   *   externally. The SDK does not observe that credit directly —
+   *   balance updates flow over the user-properties channel from the
+   *   operator's side, not from this response.
+   * - Server-side analytics events fire downstream (not directly
+   *   observable from the SDK).
+   *
+   * **UI guidance**: see [UI Guide — `claimBonus`](../../docs/ui/bonuses/UIGuide_claimBonus.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param bonus_id  The `bonus_id` from a `TBonus` returned by
+   *                  {@link getBonuses}.
+   * @returns `{ err_code, err_message, success? }`; success when
+   *          `err_code === 0` (or `err_code === -1` when treated as
+   *          idempotent no-op). The `success` field is unreliable —
+   *          ignore it.
+   *
+   * @example
+   * ```ts
+   * const bonuses = await window._smartico.api.getBonuses({
+   *   onUpdate: (refreshed) => console.log('[smartico] bonuses refreshed — re-render from this array', refreshed),
+   * });
+   * const bonus = bonuses.find(b => b.bonus_id === bonusId);
+   *
+   * if (!bonus) {
+   *   console.log('[smartico] bonus no longer visible — refresh list and hide CTA');
+   *   return;
+   * }
+   * if (!bonus.is_redeemable) {
+   *   console.log('[smartico] bonus is not claimable (auto-redeemed or already finalised) — keep CTA hidden');
+   *   return;
+   * }
+   *
+   * console.log('[smartico] claim starting — set in-flight flag, show loading dots on the Claim button, keep the modal open');
+   * const r = await window._smartico.api.claimBonus(bonus.bonus_id);
+   * console.log('[smartico] claim response received — clear in-flight flag');
+   *
+   * if (r.err_code === 0 || r.err_code === -1) {
+   *   console.log('[smartico] claim succeeded (or was already done) — show a success toast; the getBonuses onUpdate above will fire with the refreshed list');
+   * } else if (r.err_code === 9999) {
+   *   console.error('[smartico] uncaught server exception — show a generic error toast and allow retry');
+   * } else {
+   *   console.error('[smartico] claim failed — surface this error message to the user; the bonus will move to REDEEM_FAILED state and remain claimable for a retry:', r.err_message);
+   * }
+   * ```
    */
   async claimBonus(bonus_id) {
     const r = await this.api.bonusClaimItem(this.userExtId, bonus_id);
@@ -4481,7 +4984,7 @@ class WSAPITournaments extends WSAPIStore {
    *
    * 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
+   * to pick a clan first via `joinClan`, then call
    * `registerInTournament` after the clan-join resolves. See "Error
    * codes" `1010` below for the server-side safety net.
    *
@@ -4490,8 +4993,8 @@ class WSAPITournaments extends WSAPIStore {
    *   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.
+   *   (e.g. open a clan-pick modal driven by `getClans` +
+   *   `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.
@@ -5049,23 +5552,81 @@ class WSAPIJackpots extends WSAPIClans {
     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
+  /**
+   * Returns the user-eligible jackpots active for the label, fused with their live
+   * pot values. Each entry carries the static template (name, description, opt-in
+   * state, eligible games, currency) plus a freshly-fetched `pot` snapshot.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.jackpotGet({ related_game_id: 'wooko-slot' }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * Designed to be polled at high frequency (every 1 second is fine) — the SDK
+   * splits the response into a 30-second template cache and a 1-second pot-value
+   * cache so consumers can render a live-counting pot amount without hammering
+   * the server for the static template data.
    *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').jackpotGet({ related_game_id: 'wooko-slot' }).then((result) => {
-   *      console.log(result);
-   * });
+   * @remarks
+   * **Preconditions**
+   * - No prerequisite calls.
+   * - Visitor mode supported via `_smartico.vapi(lang).jackpotGet(...)`.
+   *
+   * **Server-side eligibility filtering**
+   * Jackpots are filtered server-side by the user's segments before being
+   * returned. Templates the user is ineligible for never appear in this
+   * response — there is no "locked" state to render. An empty result for a
+   * known-good user typically means none of the configured templates match
+   * the user's segments / level / brand.
+   *
+   * **Filter behavior**
+   * Passing `related_game_id` returns only jackpots linked to that game (from
+   * the operator's games catalog). Passing `jp_template_id` returns just that
+   * single template. With no filter, all active templates the user is
+   * eligible for are returned. Changing the filter between calls flushes both
+   * the template cache and the pot cache.
+   *
+   * **Two-tier cache**
+   * - Template definitions: 30 s cache. Re-fetched on filter change or when
+   *   opt-in / opt-out / a jackpot-win push lands.
+   * - Pot values: 1 s cache. Re-fetched on every call past the 1-second
+   *   window so a 1 Hz poll renders a smoothly counting pot.
+   *
+   * **`jp_public_meta.custom_data`**
+   * Server returns this as a JSON-encoded string; the SDK parses it inline so
+   * consumers always receive either a parsed object or the raw string.
+   *
+   * **Personal vs MultiUser jackpots** (see {@link JackpotType})
+   * - `MultiUser` (1) — shared pot; `registration_count` reflects real opted-in
+   *   user count; temperature transitions fire push events.
+   * - `Personal` (2) — independent per-user pot; `registration_count` is
+   *   always 1; temperature push events are suppressed.
+   *
+   * **Refresh**
+   * - `jp_status_id`, segment changes, and operator template edits surface
+   *   after the 30 s template cache TTL.
+   * - Opt-in / opt-out / jackpot-win push events all clear the template and
+   *   pot caches — the next call re-fetches.
+   *
+   * **Visitor mode**: supported.
+   *
+   * **UI guidance**: see [UI Guide — `jackpotGet`](../../docs/ui/jackpots/UIGuide_jackpotGet.md).
+   *
+   * @param filter                     Optional filter narrowing the result set.
+   * @param filter.related_game_id     Limit to jackpots linked to this game ID
+   *                                    (from the operator's games catalog).
+   * @param filter.jp_template_id      Limit to a single template.
+   * @returns Array of {@link JackpotDetails} — empty if the user is eligible
+   * for no active jackpots.
+   *
+   * @example
+   * ```ts
+   * // Poll every second for live pot counter
+   * setInterval(async () => {
+   *     const jackpots = await window._smartico.api.jackpotGet();
+   *     for (const jp of jackpots) {
+   *         console.log('[smartico] update pot widget for', jp.jp_public_meta.name, '— amount:', jp.pot.current_pot_amount_user_currency, jp.user_currency, '— temperature:', jp.pot.current_pot_temperature);
+   *     }
+   * }, 1000);
+   *
+   * // Filtered fetch for a specific game tile
+   * const linked = await window._smartico.api.jackpotGet({ related_game_id: 'gold-slot2' });
+   * console.log('[smartico] linked jackpots for game:', linked.length);
    * ```
    */
   async jackpotGet(filter) {
@@ -5102,18 +5663,68 @@ class WSAPIJackpots extends WSAPIClans {
     });
   }
   /**
-   * 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.
+   * Opts the authenticated user into a jackpot. From this point on, the user
+   * contributes to the pot (per the template's `contribution_type` and
+   * `contribution_value`) and is eligible to win when the pot explodes.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.jackpotOptIn({ jp_template_id: 123 }).then((result) => {
-   *      console.log('Opted in to the jackpot');
-   * });
-   * ```
+   * On success the SDK clears the jackpot caches — the next
+   * {@link jackpotGet} call returns the updated `is_opted_in: true` and an
+   * incremented `registration_count`.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   * - `jp_template_id` is mandatory — the SDK throws synchronously if missing.
+   * - The jackpot must currently be active and the user must be in its
+   *   eligibility segment. Ineligible jackpots are filtered out of
+   *   {@link jackpotGet} entirely, so a card the user sees is opt-in-able.
+   *
+   * **Error handling**
+   * The server returns a non-zero `errCode` with a human-readable `errMsg`
+   * for any failure. Common causes:
+   * - User is in a control group.
+   * - Jackpot template is not active (status changed since the user opened
+   *   the card).
+   * - User is already opted in (the SDK has no client-side guard against a
+   *   double-tap; the server enforces).
+   * - DB race / generic server error.
+   *
+   * The SDK does NOT enumerate distinct numeric codes for each cause — branch
+   * on `errCode === 0` for success and surface `errMsg` as-is for failures.
+   *
+   * **Idempotency / re-opt-in semantics**
+   * - **Already opted in** → returns non-zero `errCode` ("User already opted in").
+   * - **Previously opted in then opted out** → succeeds silently; the server
+   *   re-activates the registration. This is not an error path — a user can
+   *   freely cycle opt-in / opt-out.
+   *
+   * **Refresh after success**
+   * - The SDK clears the template, pot, and winners caches.
+   * - The next {@link jackpotGet} call returns `is_opted_in: true` for this
+   *   template.
+   *
+   * **Side effects**
+   * Fires a `JACKPOT_OPT_IN` engagement event (visible to operator-side
+   * automation rules). Does NOT immediately move points / gems — contributions
+   * happen per-bet via the user's gameplay, not on opt-in.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `jackpotOptIn`](../../docs/ui/jackpots/UIGuide_jackpotOptIn.md).
    *
+   * @param filter.jp_template_id  ID of the jackpot template to join.
+   * @returns {@link JackpotsOptinResponse} — `errCode === 0` on success.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.jackpotOptIn({ jp_template_id: 42 });
+   *
+   * if (r.errCode === 0) {
+   *     console.log('[smartico] opted in — refresh jackpot card to show opt-out CTA');
+   * } else {
+   *     console.error('[smartico] opt-in failed — show this message in an error toast:', r.errMsg);
+   * }
+   * ```
    */
   async jackpotOptIn(filter) {
     if (!filter.jp_template_id) {
@@ -5123,18 +5734,63 @@ class WSAPIJackpots extends WSAPIClans {
     return result;
   }
   /**
-   * 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.
+   * Opts the authenticated user out of a jackpot. From this point on the user
+   * no longer contributes to the pot and is not eligible to win.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.jackpotOptOut({ jp_template_id: 123 }).then((result) => {
-   *      console.log('Opted out from the jackpot');
-   * });
-   * ```
+   * The user can re-join later via {@link jackpotOptIn} — opt-out is not
+   * permanent.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   * - `jp_template_id` is mandatory — the SDK throws synchronously if missing.
+   *
+   * **Error handling**
+   * The server returns a non-zero `errCode` with a human-readable `errMsg` for
+   * any failure. Common causes:
+   * - User has never opted in OR is already opted out — server returns
+   *   non-zero `errCode` for the "already opted out" case. Calling opt-out
+   *   on a jackpot the user has never registered for typically returns
+   *   success (the server finds no registration row to update).
+   * - DB race / generic server error.
+   *
+   * Unlike {@link jackpotOptIn}, opt-out does NOT check the template's status
+   * — the user can opt out of a jackpot that has been deactivated by the
+   * operator.
+   *
+   * **Idempotency**
+   * - First opt-out → success.
+   * - Second opt-out → non-zero `errCode` ("Already opted out").
+   * - Opt-out of a never-joined jackpot → typically succeeds silently
+   *   (no registration row to act on).
+   *
+   * **Refresh after success**
+   * - The SDK clears the template, pot, and winners caches.
+   * - The next {@link jackpotGet} call returns `is_opted_in: false` for this
+   *   template and a decremented `registration_count`.
    *
+   * **Side effects**
+   * Fires a `JACKPOT_OPT_OUT` engagement event for operator-side automation
+   * rules. The user's existing contributions to the current pot remain in
+   * place — opt-out stops future contributions but does not refund past ones.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `jackpotOptOut`](../../docs/ui/jackpots/UIGuide_jackpotOptOut.md).
+   *
+   * @param filter.jp_template_id  ID of the jackpot template to leave.
+   * @returns {@link JackpotsOptoutResponse} — `errCode === 0` on success.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.jackpotOptOut({ jp_template_id: 42 });
+   *
+   * if (r.errCode === 0) {
+   *     console.log('[smartico] opted out — refresh jackpot card to show join CTA');
+   * } else {
+   *     console.error('[smartico] opt-out failed — show this message in an error toast:', r.errMsg);
+   * }
+   * ```
    */
   async jackpotOptOut(filter) {
     if (!filter.jp_template_id) {
@@ -5144,25 +5800,64 @@ class WSAPIJackpots extends WSAPIClans {
     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.
+   * Returns past winners of a specific jackpot template, paginated. Use to
+   * power a "Recent winners" panel inside the jackpot detail modal.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.getJackpotWinners({
-   *      jp_template_id: 123,
-   * }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * **Important**: respect the `expose_winners_over_api` flag on the jackpot's
+   * {@link JackpotDetails} before calling this method. The server-side handler
+   * does NOT enforce that flag — it is a UI-only gate. Custom UIs that ignore
+   * the flag will display winners the operator intended to keep private.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   * - `jp_template_id` is mandatory — the SDK throws synchronously if missing.
+   * - The consumer SHOULD check
+   *   {@link JackpotDetails.expose_winners_over_api} before calling, since
+   *   the server does not enforce it.
+   *
+   * **Pagination**
+   * Server default page size is 20. Pass `limit` and `offset` to paginate
+   * (e.g. infinite-scroll). The wire response carries a `has_more` flag, but
+   * this SDK method returns only the `winners` array — detect end-of-list by
+   * a returned array shorter than `limit`.
+   *
+   * **Currency caveat**
+   * Winner amounts in the response (`winner.winning_amount_jp_currency`) are
+   * in the jackpot's NATIVE currency, NOT the user's wallet currency. If a
+   * user-currency display is needed, the consumer must convert client-side.
+   *
+   * **Refresh**
+   * - The SDK caches per `jp_template_id` for 30 seconds.
+   * - Caches clear on jackpot-win push events and on opt-in / opt-out.
+   *
+   * **Error handling**
+   * Non-zero `errCode` on control-group users or generic server errors. The
+   * SDK does NOT enumerate distinct codes — branch on `errCode === 0` and
+   * surface `errMsg` on failure.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `getJackpotWinners`](../../docs/ui/jackpots/UIGuide_getJackpotWinners.md).
+   *
+   * @returns Array of {@link JackpotWinnerHistory} entries newest-first.
+   *
+   * @example
+   * ```ts
+   * const [jp] = await window._smartico.api.jackpotGet({ jp_template_id: 42 });
+   *
+   * if (!jp || !jp.expose_winners_over_api) {
+   *     console.log('[smartico] winners hidden by operator config — hide the winners tab');
+   *     return;
+   * }
    *
-   * @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
+   * const winners = await window._smartico.api.getJackpotWinners({
+   *     jp_template_id: 42,
+   *     limit:          20,
+   *     offset:         0,
+   * });
+   * console.log('[smartico] render', winners.length, 'recent winner rows (amounts in', jp.jp_currency + ')');
+   * ```
    */
   async getJackpotWinners({
     limit,
@@ -5172,29 +5867,67 @@ class WSAPIJackpots extends WSAPIClans {
     return OCache.use(onUpdateContextKey.JackpotWinners + jp_template_id, ECacheContext.WSAPI, () => this.api.getJackpotWinnersT(this.userExtId, limit, offset, jp_template_id), JACKPOT_WINNERS_CACHE_SEC);
   }
   /**
-   * Returns the eligible games for the jackpot with the specified jp_template_id.
+   * Returns the casino games eligible to contribute to a specific jackpot —
+   * the catalog the user must play to grow the pot. Use to power an
+   * "Eligible games" carousel inside the jackpot detail modal.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.getJackpotEligibleGames({ jp_template_id: 123 }).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * **Shortcut**: when the jackpot's
+   * {@link JackpotDetails.ach_related_game_allow_all} flag is `true`, every
+   * game in the operator catalog contributes — there's no point calling this
+   * method (the result would be the full catalog). The default Smartico UI
+   * hides the Eligible Games tab entirely in that case.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   * - `jp_template_id` is mandatory.
    *
-   */
-  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);
-  }
+   * **`onUpdate` caveat**
+   * The `onUpdate` callback is accepted to match the SDK's subscription
+   * contract but is NOT auto-invoked by any current server push. It will only
+   * fire if a consumer (or a future SDK version) explicitly pushes an update.
+   * Treat it as a no-op for now.
+   *
+   * **Refresh**
+   * - The SDK caches per `jp_template_id` for 30 seconds.
+   * - Cache does NOT clear on opt-in / opt-out / jackpot-win — eligible-game
+   *   lists rarely change during a session. Wait for the 30 s TTL.
+   *
+   * **Error handling**
+   * Non-zero `errCode` on control-group users or generic server errors.
+   * Branch on `errCode === 0` and surface `errMsg` on failure.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `getJackpotEligibleGames`](../../docs/ui/jackpots/UIGuide_getJackpotEligibleGames.md).
+   *
+   * @returns {@link TGetJackpotEligibleGamesResponse} —
+   * `{ eligible_games: JackpotEligibleGame[] }`.
+   *
+   * @example
+   * ```ts
+   * const [jp] = await window._smartico.api.jackpotGet({ jp_template_id: 42 });
+   *
+   * if (jp?.ach_related_game_allow_all) {
+   *     console.log('[smartico] all games eligible — hide the eligible-games tab');
+   *     return;
+   * }
+   *
+   * const r = await window._smartico.api.getJackpotEligibleGames({ jp_template_id: 42 });
+   * console.log('[smartico] render', r.eligible_games.length, 'eligible game tiles');
+   * ```
+   */
+  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 */
@@ -5204,26 +5937,112 @@ class WSAPIRaffles extends WSAPIJackpots {
     this.updateEntity(onUpdateContextKey.Raffles, payload);
   }
   /**
-   * 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.
+   * Returns all raffles visible to the current user, each carrying an
+   * embedded `draws[]` array with per-draw state (current state, ticket
+   * counts, opt-in status, prize structure). Use this to power a
+   * raffles lobby screen and to drive per-draw CTAs (opt-in, view
+   * winners, claim).
+   *
+   * The embedded `draws[i]` objects are sufficient for rendering all
+   * draw cards — winner details with usernames / avatars require a
+   * follow-up {@link getRaffleDrawRun} call (the embedded form carries
+   * only `winners_total` / `winners_limit` / `winners_offset` metadata,
+   * not individual winner rows).
    *
-   * **Example**:
+   * @remarks
+   * **Subscription model (`onUpdate`)**
+   * The callback receives the FULL refreshed raffle list (never a
+   * diff/patch). Each subsequent call to `getRaffles({ onUpdate })`
+   * REPLACES the prior callback. Pass `onUpdate: undefined` (or omit
+   * it) to keep the prior callback in place; the callback is never
+   * auto-cleared.
    *
-   * ```
-   * _smartico.api.getRaffles().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * **Update triggers** — the callback fires when:
    *
-   * **Example in the Visitor mode**:
+   * 1. {@link claimRafflePrize} resolves on this connection (any
+   *    response code) — the refreshed list reflects the new
+   *    `has_unclaimed_prize` / `claimed_date` state.
+   * 2. {@link requestRaffleOptin} resolves on this connection (any
+   *    response code) — the refreshed list reflects the new
+   *    `user_opted_in` state on the affected draw.
+   *
+   * Does NOT fire for: server-side draw executions, ticket increments
+   * (other users earning tickets), or operator-side raffle/draw config
+   * changes. Those changes surface only on the next cache miss (after
+   * the 30 s TTL) — poll manually if your UI needs sub-30s freshness
+   * during an in-progress draw.
+   *
+   * **Reading state from the returned raffle**
+   * - `current_tickets_count` vs `max_tickets_count` drives the
+   *   `ticket_cap_visualization` banner (enum
+   *   {@link RaffleTicketCapVisualization}: `Empty` = no banner,
+   *   `Counter` = show "X tickets remaining", `Message` = show
+   *   sold-out message).
+   * - Within each draw, `current_state`
+   *   ({@link RaffleDrawInstanceState}) buckets the draw into Open
+   *   (accepting tickets), WinnerSelection (currently drawing), or
+   *   Executed (winners selected).
+   * - `execution_type` ({@link RaffleDrawTypeExecution}) distinguishes
+   *   one-shot (`ExecDate`), repeating (`Recurring`), or special
+   *   one-shot (`Grand`) draws. Recurring draws share a stable
+   *   `draws[i].id` (the schedule definition) across runs — `run_id`
+   *   is the per-execution instance.
    *
-   * ```
-   * _smartico.vapi('EN').getRaffles().then((result) => {
-   *      console.log(result);
+   * **Cache TTL**: the SDK caches the response for 30 seconds. Cache
+   * is fully cleared on login / logout. The server also invalidates
+   * the SDK cache when a draw executes on the server side.
+   *
+   * **Idempotency / Side effects**: safe. Read-only.
+   *
+   * **UI guidance**: see [UI Guide — `getRaffles`](../../docs/ui/raffles/UIGuide_getRaffles.md).
+   *
+   * **Visitor mode**: supported. The same shape is returned, scoped
+   * to the brand's public raffles. Per-user fields (`my_tickets_count`,
+   * `my_last_tickets`, `user_opted_in`) are not meaningful for
+   * visitors. The `onUpdate` callback is accepted but never fires
+   * because the mutation methods that trigger it
+   * ({@link claimRafflePrize}, {@link requestRaffleOptin}) are not
+   * available / not effective in visitor mode.
+   *
+   * @param params              Optional. Omit to fetch without subscribing.
+   * @param params.onUpdate     Callback invoked with the full refreshed
+   *                            raffles list after every
+   *                            {@link claimRafflePrize} or
+   *                            {@link requestRaffleOptin} round-trip
+   *                            on this connection.
+   * @returns                   Promise resolving to the raffles list.
+   *
+   * @example
+   * ```ts
+   * const raffles = await window._smartico.api.getRaffles({
+   *   onUpdate: (refreshed) => {
+   *     console.log('[smartico] raffles refreshed (after claim/optin) — re-render from this array:', refreshed);
+   *   },
    * });
-   * ```
    *
+   * for (const raffle of raffles) {
+   *   console.log('[smartico] render raffle', raffle.id, '—', raffle.name, ':', raffle.draws.length, 'draws');
+   *
+   *   // Bucket draws: active/upcoming first (sorted by execution_ts ASC), then executed last.
+   *   const sorted = [...raffle.draws].sort((a, b) => {
+   *     const aDone = a.current_state === 3;  // Executed
+   *     const bDone = b.current_state === 3;
+   *     if (aDone !== bDone) return aDone ? 1 : -1;  // executed sink to the bottom
+   *     return a.execution_ts - b.execution_ts;
+   *   });
+   *
+   *   for (const d of sorted) {
+   *     if (d.requires_optin && !d.user_opted_in && d.is_active && d.current_state !== 3) {
+   *       console.log('[smartico] draw', d.run_id, '— show OPT IN CTA (requires_optin + not yet opted in + still active)');
+   *     }
+   *     if (d.current_state === 3) {
+   *       console.log('[smartico] draw', d.run_id, 'executed — fetch winner details via getRaffleDrawRun');
+   *     }
+   *   }
+   * }
+   *
+   * // For winner detail on an executed draw, call getRaffleDrawRun separately.
+   * ```
    */
   async getRaffles({
     onUpdate
@@ -5234,27 +6053,106 @@ class WSAPIRaffles extends WSAPIJackpots {
     return OCache.use(onUpdateContextKey.Raffles, ECacheContext.WSAPI, () => this.api.getRafflesT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * 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.
+   * Returns the full detail of a single raffle draw run — same shape
+   * as the embedded `TRaffleDraw` in {@link getRaffles}, but populated
+   * with paginated `prizes[].winners[]` rows including usernames and
+   * avatars. Use this to render a draw detail / winners screen, or to
+   * page through the winner list of an executed draw.
    *
+   * Each call is a fresh server round-trip — there is no client cache.
+   * Re-call to refresh.
    *
-   * **Example**:
+   * @remarks
+   * **Preconditions**
+   * Pass `raffle_id` (the parent raffle's `id`) and `run_id` (the
+   * specific run instance — `TRaffleDraw.run_id` from
+   * {@link getRaffles}'s embedded draws). Note that
+   * `TRaffleDraw.id` is the *schedule_id* (stable across runs of a
+   * recurring draw) — that's NOT what this method takes; it takes the
+   * per-instance `run_id`.
    *
-   * ```javascript
-   * _smartico.api.getRaffleDrawRun({raffle_id: 156, run_id: 145}).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * **Refresh model**
+   * - **No subscription.** One-shot promise.
+   * - **No client cache.** Every call sends a network request.
+   * - **No push event** refreshes the response. Live winner-list
+   *   updates require a fresh call.
+   * - The default Smartico UI polls this method on a variable cadence
+   *   while a draw is in flight: every 3 s during `WinnerSelection`,
+   *   every 10 s when the countdown is under 5 minutes, every 30 s
+   *   otherwise.
+   *
+   * **Winner pagination**
+   * `winners_from` / `winners_to` define a half-open range of winner
+   * indices. The default window is `0–20` (20 winners). The server
+   * caps the window at 50 rows per call — passing a larger range
+   * silently truncates. For "load more" pagination, advance
+   * `winners_from` by the prior page size and pass the same
+   * `winners_to` offset. `winners_total` on the returned
+   * `TRaffleDraw` is the authoritative total count for pagination.
+   *
+   * The current user's own winning rows (if any) are server-sorted
+   * to the top of the result.
+   *
+   * **Throws**
+   * Both `raffle_id` and `run_id` are required — the SDK throws
+   * synchronously when either is missing or falsy.
+   *
+   * **Idempotency / Side effects**: safe. Read-only.
+   *
+   * **UI guidance**: see [UI Guide — `getRaffleDrawRun`](../../docs/ui/raffles/UIGuide_getRaffleDrawRun.md).
+   *
+   * **Visitor mode**: supported.
+   *
+   * @param props.raffle_id      The parent raffle's `id` (from `TRaffle.id`).
+   * @param props.run_id         The draw run instance ID (from
+   *                             `TRaffleDraw.run_id`, not `TRaffleDraw.id`).
+   * @param props.winners_from   First winner index to return (0-based).
+   *                             Defaults to `0`.
+   * @param props.winners_to     Last winner index (exclusive).
+   *                             Defaults to `20`. Server caps the
+   *                             window at 50 rows per call.
+   * @returns                    Promise resolving to `TRaffleDraw`
+   *                             with `prizes[].winners[]` populated
+   *                             and `winners_total` set.
    *
-   * **Example in the Visitor mode**:
+   * @example
+   * ```ts
+   * const raffles = await window._smartico.api.getRaffles();
+   * const raffle = raffles[0];
+   * const draw = raffle.draws.find(d => d.current_state === 3);  // Executed
    *
+   * if (!draw) {
+   *   console.log('[smartico] no executed draw — skip detail view');
+   *   return;
+   * }
    *
-   * ```javascript
-   * _smartico.vapi('EN').getRaffleDrawRun({ raffle_id: 156, run_id: 145 }).then((result) => {
-   *      console.log(result);
+   * // First page of winners.
+   * const detail = await window._smartico.api.getRaffleDrawRun({
+   *   raffle_id: raffle.id,
+   *   run_id: draw.run_id,   // NOTE: run_id, NOT draw.id
+   *   winners_from: 0,
+   *   winners_to: 20,
    * });
-   * ```
    *
+   * for (const prize of detail.prizes) {
+   *   console.log('[smartico] prize', prize.name, '— winners on this page:', prize.winners.length);
+   *   const myWin = prize.winners.find(w => w.username === currentUsername);  // or another match
+   *   if (myWin) {
+   *     console.log('[smartico] current user won this prize — surface a Claim CTA if not yet claimed');
+   *   }
+   * }
+   *
+   * // Load more — pagination via winners_from / winners_to.
+   * if ((detail.winners_total ?? 0) > 20) {
+   *   const next = await window._smartico.api.getRaffleDrawRun({
+   *     raffle_id: raffle.id,
+   *     run_id: draw.run_id,
+   *     winners_from: 20,
+   *     winners_to: 40,
+   *   });
+   *   console.log('[smartico] page 2 loaded — append', next.prizes.flatMap(p => p.winners).length, 'winners');
+   * }
+   * ```
    */
   async getRaffleDrawRun(props) {
     if (!props.raffle_id || !props.run_id) {
@@ -5263,25 +6161,76 @@ class WSAPIRaffles extends WSAPIJackpots {
     return await this.api.getRaffleDrawRunT(this.userExtId, props.raffle_id, props.run_id, props.winners_from, props.winners_to);
   }
   /**
-   * 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
+   * Returns the history of past-executed draw runs for a raffle —
+   * optionally scoped to a single recurring draw schedule. Each row
+   * is a previously-executed run with its scheduled and
+   * actual-execution timestamps, the user's win status, and an
+   * unclaimed-prize flag for surfacing a Claim CTA on history rows.
+   *
+   * @remarks
+   * **Preconditions**
+   * `raffle_id` is required. `draw_id` is optional — when omitted,
+   * the response includes history for ALL draws of the raffle; when
+   * supplied, it scopes to that one draw's recurring history. The
+   * `draw_id` to pass is `TRaffleDraw.id` (the schedule_id, stable
+   * across runs), not `run_id`.
    *
+   * **Server-side filtering**
+   * Draws configured by the operator to hide their history are
+   * excluded from the response automatically. Cancelled runs are
+   * also excluded.
+   *
+   * **Sort order**
+   * Server returns rows by scheduled `execution_ts` descending
+   * (newest first). No client-side sort required.
+   *
+   * **Refresh model**
+   * - **No subscription.** One-shot promise.
+   * - **No client cache.** Every call hits the server.
+   * - **No push event** refreshes the response. Re-call manually to
+   *   pick up newly-executed runs or `has_unclaimed_prize` flips
+   *   after a {@link claimRafflePrize} call.
    *
-   * **Example**:
+   * **Idempotency / Side effects**: safe. Read-only.
    *
-   * ```javascript
-   * _smartico.api.getRaffleDrawRunsHistory({ raffle_id: 156, draw_id: 432 }).then((result) => {
-   *      console.log(result);
+   * **UI guidance**: see [UI Guide — `getRaffleDrawRunsHistory`](../../docs/ui/raffles/UIGuide_getRaffleDrawRunsHistory.md).
+   *
+   * **Visitor mode**: supported. The same shape is returned with
+   * `is_winner` and `has_unclaimed_prize` always `false` for visitors.
+   *
+   * @param props.raffle_id  The parent raffle's `id` (from `TRaffle.id`).
+   *                         Required.
+   * @param props.draw_id    Optional — the draw's schedule_id
+   *                         (`TRaffleDraw.id`). When set, scopes the
+   *                         history to that one draw's runs. When
+   *                         omitted, includes all draws of the raffle.
+   * @returns                Promise resolving to a `TRaffleDrawRun[]`
+   *                         ordered newest-first. Empty if no executed
+   *                         runs exist.
+   *
+   * @example
+   * ```ts
+   * const raffles = await window._smartico.api.getRaffles();
+   * const raffle = raffles[0];
+   *
+   * // History across all draws of the raffle.
+   * const allHistory = await window._smartico.api.getRaffleDrawRunsHistory({
+   *   raffle_id: raffle.id,
    * });
-   * ```
    *
-   * **Example in the Visitor mode**:
+   * // Highlight rows where the user has an unclaimed prize.
+   * const unclaimed = allHistory.filter(r => r.has_unclaimed_prize);
+   * if (unclaimed.length > 0) {
+   *   console.log('[smartico] surface a "Claim" CTA on these', unclaimed.length, 'history rows:', unclaimed.map(r => r.run_id));
+   * }
    *
-   * ```javascript
-   * _smartico.vapi('EN').getRaffleDrawRunsHistory({ raffle_id: 156, draw_id: 432 }).then((result) => {
-   *      console.log(result);
+   * // Scoped history of one recurring draw (use draw.id, the schedule_id).
+   * const oneDrawHistory = await window._smartico.api.getRaffleDrawRunsHistory({
+   *   raffle_id: raffle.id,
+   *   draw_id: raffle.draws[0].id,   // schedule_id (stable across recurring runs)
    * });
+   * console.log('[smartico] render history rows for the daily draw — newest first:', oneDrawHistory.length, 'rows');
    * ```
-   *
    */
   async getRaffleDrawRunsHistory(props) {
     const res = await this.api.getRaffleDrawRunsHistory(this.userExtId, props);
@@ -5291,25 +6240,113 @@ class WSAPIRaffles extends WSAPIJackpots {
     return drawRunHistoryTransform(res);
   }
   /**
-   * Returns `err_code` and `err_message` after the call; `err_code` 0 means the request succeeded.
+   * Claims a raffle prize the user has won. Call this when the user
+   * has a winning row with `should_claim === true` and an unclaimed
+   * `won_id` (read from a `TRafflePrizeWinner` on a
+   * {@link getRaffleDrawRun} result, or surfaced by `has_unclaimed_prize`
+   * on a {@link getRaffleDrawRunsHistory} row that the consumer drills
+   * into).
    *
+   * On success (`errorCode === 0`), the server records the claim and
+   * triggers prize delivery through the operator's integration —
+   * delivery is server-side, not part of this response.
    *
-   * **Example**:
+   * @remarks
+   * **Result shape note**: this method returns
+   * `TransformedRaffleClaimPrizeResponse` with `errorCode` /
+   * `errorMessage` (camelCase full-word) — different from most other
+   * SDK result types which use `err_code` / `err_message` (snake_case
+   * short-word). Branch on the camelCase keys when reading this
+   * method's result.
    *
-   * ```javascript
-   * _smartico.api.claimRafflePrize({won_id:251}).then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * **Preconditions**
+   * Pass a `won_id` that identifies an unclaimed winning row for the
+   * current user. The `won_id` comes from
+   * `TRafflePrizeWinner.raf_won_id` returned by
+   * {@link getRaffleDrawRun}.
+   *
+   * **Error codes** (in `errorCode`)
+   * - `0` — success; the claim is recorded and prize delivery is
+   *   queued server-side.
+   * - `1` — generic claim failure. The `errorMessage` distinguishes
+   *   the specific cause (the server uses one error code for several
+   *   distinct conditions): the prize has already been claimed, the
+   *   `won_id` doesn't match a winning row for this user, or the user
+   *   is in a control group for this raffle. Treat `1` as a retryable
+   *   error if the message suggests a transient condition; treat as
+   *   idempotent success if the message indicates already-claimed
+   *   (the underlying state is what the consumer wants either way —
+   *   the prize is claimed).
+   * - other non-zero — generic server error. Surface `errorMessage`
+   *   if any.
+   *
+   * **Claim window**
+   * There is no server-enforced claim deadline. Won prizes remain
+   * claimable indefinitely until the operator archives them.
+   *
+   * **Idempotency**: NOT idempotent. A second call on the same
+   * `won_id` returns `errorCode === 1` with `errorMessage` indicating
+   * the prize has already been claimed. The SDK does NOT enforce an
+   * in-flight lock. Guard the call site against double-clicks (set
+   * a local "claiming" flag on click, clear it on response).
    *
-   * **Example in the Visitor mode**:
+   * **Refresh after success (and after failure)**
+   * The SDK automatically refreshes the raffles cache on every
+   * response — both success and failure paths fire the `onUpdate`
+   * callback registered via {@link getRaffles}. After `errorCode === 0`,
+   * the affected `TRaffleDrawRun.has_unclaimed_prize` (in history)
+   * and the winner row's `claimed_date` reflect the claim on the next
+   * refresh.
+   *
+   * **Side effects** (on `errorCode === 0`)
+   * - The winner row's `claimed_date` is set server-side.
+   * - Prize delivery is queued for the operator's integration to
+   *   process. Balance / bonus / inbox updates that result from the
+   *   delivery arrive through their own channels — not in this
+   *   response.
+   *
+   * **Throws**
+   * `won_id` is required — the SDK throws synchronously when missing
+   * or falsy.
+   *
+   * **UI guidance**: see [UI Guide — `claimRafflePrize`](../../docs/ui/raffles/UIGuide_claimRafflePrize.md).
+   *
+   * **Visitor mode**: not meaningfully supported. The SDK does not
+   * block the call, but visitor sessions have no win history and the
+   * server will reject it.
+   *
+   * @param props.won_id  The winning row's `raf_won_id` (from
+   *                      `TRafflePrizeWinner` returned by
+   *                      {@link getRaffleDrawRun}).
+   * @returns `{ errorCode, errorMessage? }`; success when
+   *          `errorCode === 0`. Note camelCase keys (see "Result
+   *          shape note" above).
    *
-   * ```javascript
-   * _smartico.vapi('EN').claimRafflePrize({ won_id: 251 }).then((result) => {
-   *      console.log(result);
+   * @example
+   * ```ts
+   * const detail = await window._smartico.api.getRaffleDrawRun({
+   *   raffle_id: raffleId,
+   *   run_id: runId,
    * });
-   * ```
+   * const myWin = detail.prizes.flatMap(p => p.winners).find(w => /* user match here *\/ true);
+   *
+   * if (!myWin || !myWin.raf_won_id || myWin.claimed_date) {
+   *   console.log('[smartico] nothing to claim — keep CTA hidden');
+   *   return;
+   * }
+   *
+   * console.log('[smartico] claim starting — set in-flight flag, show loading dots on the Claim button, keep the modal open');
+   * const r = await window._smartico.api.claimRafflePrize({ won_id: myWin.raf_won_id });
+   * console.log('[smartico] claim response received — clear in-flight flag');
    *
+   * if (r.errorCode === 0) {
+   *   console.log('[smartico] claim succeeded — show a success toast; getRaffles onUpdate above will fire with refreshed state; prize delivery happens server-side');
+   * } else if (r.errorCode === 1 && r.errorMessage?.toLowerCase().includes('already claimed')) {
+   *   console.log('[smartico] prize was already claimed (perhaps from another tab) — treat as success, hide the Claim CTA');
+   * } else {
+   *   console.error('[smartico] claim failed — surface this error message to the user and allow retry:', r.errorMessage);
+   * }
+   * ```
    */
   async claimRafflePrize(props) {
     if (!props.won_id) {
@@ -5321,9 +6358,104 @@ class WSAPIRaffles extends WSAPIJackpots {
     return raffleClaimPrizeResponseTransform(res);
   }
   /**
-   * Requests an opt-in for the specified raffle. Returns the err_code.
+   * Opts the current user into a specific raffle draw run. Required
+   * for draws where `TRaffleDraw.requires_optin === true` — without
+   * opt-in, the user's tickets do NOT participate in that run, even
+   * if they hold tickets for the raffle.
    *
-   * **Visitor mode: not supported**
+   * Opt-in is per-run: a recurring draw's next run requires a fresh
+   * opt-in. The user's `TRaffleDraw.user_opted_in` flag reflects the
+   * current state for the current run only.
+   *
+   * @remarks
+   * **Preconditions**
+   * Read the candidate draw from {@link getRaffles}'s embedded
+   * `draws[]` and gate the call on
+   * `requires_optin === true && !user_opted_in && is_active &&
+   * current_state !== Executed`. Calling without these guards may
+   * return a non-zero `err_code`.
+   *
+   * **Argument mapping** — the three IDs come from different fields:
+   * - `raffle_id` — the parent raffle's `TRaffle.id`
+   * - `draw_id` — `TRaffleDraw.id` (schedule_id, stable across runs)
+   * - `raffle_run_id` — `TRaffleDraw.run_id` (instance ID for this
+   *   specific run)
+   *
+   * **Error codes** (in `err_code`)
+   * - `0` — success; the user is opted into this run. Tickets
+   *   collected after the run's `ticket_start_ts` will participate.
+   * - `1` — generic opt-in failure. The `err_message` distinguishes
+   *   the specific cause: the draw doesn't require opt-in
+   *   (`requires_optin === false`), `raffle_id` doesn't match the
+   *   `draw_id`, the user is already opted in (or the draw has
+   *   completed), or the user is in a control group for this raffle.
+   * - other non-zero — generic server error. Surface `err_message`.
+   *
+   * **Idempotency**: NOT idempotent. A second call on the same
+   * `raffle_run_id` returns `err_code === 1` with `err_message`
+   * indicating the user is already opted in. Treat as success in
+   * the UI — the underlying state is what the consumer wants.
+   * Guard the call site against double-clicks.
+   *
+   * **Refresh after success (and after failure)**
+   * The SDK automatically refreshes the raffles cache on every
+   * response and fires the `onUpdate` callback registered via
+   * {@link getRaffles}. After `err_code === 0`, the affected draw's
+   * `user_opted_in` flips to `true` on the refreshed list.
+   *
+   * **Side effects** (on `err_code === 0`)
+   * - The user is registered for this run. Tickets earned within
+   *   the run's eligibility window will participate in the draw.
+   * - No balance change. No CRM-side rewards. Opt-in is a metadata
+   *   operation only.
+   *
+   * **Throws**
+   * `raffle_id`, `draw_id`, and `raffle_run_id` are all required —
+   * the SDK throws synchronously when any is missing or falsy.
+   *
+   * **UI guidance**: see [UI Guide — `requestRaffleOptin`](../../docs/ui/raffles/UIGuide_requestRaffleOptin.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param props.raffle_id      The parent raffle's `id`.
+   * @param props.draw_id        The draw's schedule_id (`TRaffleDraw.id`).
+   * @param props.raffle_run_id  The run instance ID (`TRaffleDraw.run_id`).
+   * @returns                    `{ err_code, err_message? }`; success
+   *                             when `err_code === 0` (treat
+   *                             "already opted in" as idempotent
+   *                             success).
+   *
+   * @example
+   * ```ts
+   * const raffles = await window._smartico.api.getRaffles({
+   *   onUpdate: (refreshed) => console.log('[smartico] raffles refreshed — re-render', refreshed),
+   * });
+   * const raffle = raffles[0];
+   * const draw = raffle.draws.find(d =>
+   *   d.requires_optin && !d.user_opted_in && d.is_active && d.current_state !== 3
+   * );
+   *
+   * if (!draw) {
+   *   console.log('[smartico] no opt-in-required draw available — keep CTA hidden');
+   *   return;
+   * }
+   *
+   * console.log('[smartico] opt-in starting — set in-flight flag, show loading dots on the Opt-in button');
+   * const r = await window._smartico.api.requestRaffleOptin({
+   *   raffle_id: raffle.id,
+   *   draw_id: draw.id,        // schedule_id, NOT run_id
+   *   raffle_run_id: draw.run_id,
+   * });
+   * console.log('[smartico] opt-in response received — clear in-flight flag');
+   *
+   * if (r.err_code === 0) {
+   *   console.log('[smartico] opted in successfully — show "Fully opted in" state on the draw card; onUpdate above will fire with user_opted_in: true');
+   * } else if (r.err_code === 1 && r.err_message?.toLowerCase().includes('already opted in')) {
+   *   console.log('[smartico] already opted in (perhaps from another tab) — treat as success, show "Fully opted in"');
+   * } else {
+   *   console.error('[smartico] opt-in failed — surface this error to the user:', r.err_message);
+   * }
+   * ```
    */
   async requestRaffleOptin(props) {
     if (!props.raffle_id) {
@@ -5341,29 +6473,233 @@ class WSAPIRaffles extends WSAPIJackpots {
       err_message: r.errMsg
     };
   }
+  /**
+   * Returns every prize the current user has won within a single raffle —
+   * across ALL of that raffle's draws, newest-won first — in one paginated
+   * call. Use this to power a "my prizes" screen for a raffle (prize name,
+   * prize image, the user's name/avatar) without walking
+   * {@link getRaffleDrawRunsHistory} and then paging
+   * {@link getRaffleDrawRun}'s per-draw winner lists.
+   *
+   * Each row carries its own `raf_won_id`, which IS the `won_id` to pass to
+   * {@link claimRafflePrize}: a row with `requires_claim === true` and no
+   * `claimed_date` is directly claimable.
+   *
+   * @remarks
+   * **Authentication required**
+   * Works only for an identified (logged-in) user. Visitor / anonymous
+   * sessions are rejected — call this only after identify.
+   *
+   * **Preconditions**
+   * `raffle_id` is required — the SDK throws synchronously when it is
+   * missing or falsy.
+   *
+   * **Coverage & sort order**
+   * Includes the user's wins from every draw of the raffle — recurring,
+   * one-shot, and grand draws, across all historical runs. Rows are ordered
+   * newest-win first; there is no "unclaimed first" ordering, so sort
+   * client-side if you want claimable prizes at the top.
+   *
+   * **Pagination**
+   * `offset` / `limit` page the `won_prizes[]` rows (the SDK defaults to
+   * `0` / `20`). `total` is the authoritative full count of the user's wins
+   * for this raffle across all draws — drive "load more" from it
+   * (`offset + won_prizes.length < total`). An `offset` past the end returns
+   * an empty `won_prizes[]` with the real `total` and `errCode 0` — not an
+   * error. The server does NOT clamp `limit`, so always pass an explicit,
+   * sane page size.
+   *
+   * **Rate limit**
+   * The server caps this at roughly 30 calls per minute with a ~5-second
+   * minimum gap between calls. Fetch on screen open and on explicit "load
+   * more" — don't poll it on a timer.
+   *
+   * **Error codes** (in `errCode`)
+   * - `0` — success. Also returned with an empty `won_prizes[]` and
+   *   `total 0` when the user has no wins, or is not eligible to see this
+   *   raffle.
+   * - `1` — generic server error; surface `errMsg` if present.
+   *
+   * There are no granular codes — an unknown raffle, an ineligible user,
+   * and "no wins" all surface as `errCode 0` with an empty list.
+   *
+   * **Reading the result**
+   * - Null-check `user` before reading it — it is `null` whenever
+   *   `won_prizes` is empty.
+   * - For the avatar, use `user.avatar_id` (already a full URL for a system
+   *   avatar, otherwise an avatar token to resolve against the widget's
+   *   avatar domain); `user.avatar_url` is always `null`.
+   * - Render `public_username` as-is (it is server-masked for privacy, e.g.
+   *   `"32:r*****"`) and substitute a "You" label for the current user.
+   * - Treat `claimed_date` as the claim flag: `null` until claimed, then
+   *   epoch ms.
+   *
+   * **Idempotency / Side effects**: safe and read-only — one-shot promise,
+   * no client cache, no subscription. The server caches the response
+   * briefly; a successful {@link claimRafflePrize} invalidates that cache,
+   * so a follow-up call reflects the new `claimed_date`. This method does
+   * NOT refresh the {@link getRaffles} list or fire its `onUpdate` — re-call
+   * manually to pick up newly-won prizes or a `claimed_date` flip.
+   *
+   * **UI guidance**: see [UI Guide — `getRaffleWonPrizes`](../../docs/ui/raffles/UIGuide_getRaffleWonPrizes.md).
+   *
+   * **Visitor mode**: not supported (see "Authentication required").
+   *
+   * @param props.raffle_id  The parent raffle's `id` (from `TRaffle.id`). Required.
+   * @param props.offset     Zero-based index of the first row to return. Defaults to `0`.
+   * @param props.limit      Page size. Defaults to `20`.
+   * @returns                Promise resolving to {@link GetRaffleWonPrizesResponse}
+   *                         (`user`, this page of `won_prizes`, and `total`;
+   *                         `errCode 0` on success).
+   *
+   * @example
+   * ```ts
+   * const raffles = await window._smartico.api.getRaffles();
+   * const raffle = raffles[0];
+   *
+   * // First page of the user's won prizes for this raffle.
+   * const page = await window._smartico.api.getRaffleWonPrizes({
+   *   raffle_id: raffle.id,
+   *   offset: 0,
+   *   limit: 20,
+   * });
+   *
+   * if (page.errCode !== 0) {
+   *   console.error('[smartico] could not load won prizes — show a retry state:', page.errMsg);
+   *   return;
+   * }
+   * if (page.won_prizes.length === 0) {
+   *   console.log('[smartico] no wins in this raffle (or not eligible) — render the empty state');
+   *   return;
+   * }
+   *
+   * console.log('[smartico]', page.user?.public_username, 'won', page.total, 'prizes total');
+   * for (const prize of page.won_prizes) {
+   *   console.log('[smartico] render prize card —', prize.public_meta.name, prize.public_meta.image_url);
+   *   if (prize.requires_claim && !prize.claimed_date) {
+   *     console.log('[smartico] show a Claim CTA — on click call claimRafflePrize({ won_id:', prize.raf_won_id, '})');
+   *   }
+   * }
+   *
+   * // Load more.
+   * if (page.offset + page.won_prizes.length < page.total) {
+   *   const next = await window._smartico.api.getRaffleWonPrizes({
+   *     raffle_id: raffle.id,
+   *     offset: page.offset + page.limit,
+   *     limit: 20,
+   *   });
+   *   console.log('[smartico] appended', next.won_prizes.length, 'more prizes');
+   * }
+   * ```
+   */
+  async getRaffleWonPrizes(props) {
+    var _props$offset, _props$limit;
+    if (!props.raffle_id) {
+      throw new Error('raffle_id is required');
+    }
+    return await this.api.getRaffleWonPrizes(this.userExtId, {
+      raffle_id: props.raffle_id,
+      offset: (_props$offset = props.offset) != null ? _props$offset : 0,
+      limit: (_props$limit = props.limit) != null ? _props$limit : 20
+    });
+  }
 }
 
 /** @group MiniGames */
 class WSAPIMiniGames extends WSAPIRaffles {
   /**
-   * 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.
+   * Returns all mini-game templates ("SAW" = Spin And Win — the
+   * umbrella term for wheel-spin, scratch-card, lootbox, gift-box,
+   * treasure-hunt, plinko, coin-flip, quiz, and several other formats)
+   * configured for the label. Optionally subscribes to live updates
+   * via `onUpdate`: the callback fires whenever the user's
+   * `spin_count` changes, jackpot grows, a manual spin is issued, or
+   * a spin response lands.
+   *
+   * The list is NOT filtered by spin availability — every configured
+   * template is returned, including ones the user cannot currently
+   * play. The `visibile_when_can_spin` flag on each template hints
+   * which to hide in a default lobby view (consumer-side filter).
    *
-   * **Example**:
-   * ```
-   * _smartico.api.getMiniGames().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * @remarks
+   * **Subscription model (`onUpdate`)**
+   * The callback receives the FULL refreshed template list (never a
+   * diff/patch). Each subsequent call to `getMiniGames({ onUpdate })`
+   * REPLACES the prior callback. Pass `onUpdate: undefined` (or omit
+   * it) to keep the prior callback in place; the callback is never
+   * auto-cleared.
    *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getMiniGames().then((result) => {
-   *      console.log(result);
+   * **Update triggers** — the callback fires when:
+   *
+   * 1. The server pushes a `spin_count` change (campaign award,
+   *    store purchase, BO manual issuance, mission reward).
+   * 2. Any {@link playMiniGame} or {@link playMiniGameBatch}
+   *    resolves on this connection — the cached array refreshes
+   *    with updated `spin_count`, `jackpot_current`, and any new
+   *    `next_available_spin_ts`.
+   * 3. Acknowledge responses land (via auto-acknowledge or
+   *    {@link miniGameWinAcknowledgeRequest}).
+   *
+   * Jackpot growth is observable on the refreshed `jackpot_current`
+   * field — the SDK inlines the live value into template `name` /
+   * `promo_text` / prize `name` via a `{{jackpot}}` template
+   * substitution at fetch time.
+   *
+   * **Game-type variants**
+   * All twelve `SAWGameType` values (`SpinAWheel`, `ScratchCard`,
+   * `MatchX`, `GiftBox`, `PrizeDrop`, `Quiz`, `LootboxWeekdays`,
+   * `LootboxCalendarDays`, `TreasureHunt`, `Voyager`, `Plinko`,
+   * `CoinFlip`) surface through the same template shape. Most are
+   * played via {@link playMiniGame}; the exceptions are:
+   * - `PrizeDrop` — server-push only; the consumer does NOT call
+   *   `playMiniGame`. Prizes arrive via the prize-drop push channel.
+   * - `MatchX` / `Quiz` — predictions are submitted via a separate
+   *   games server (not this SDK); the SAW spin is fired
+   *   server-internally to deduct the buy-in.
+   *
+   * **Cache TTL**: the SDK caches the response for 30 seconds. Cache
+   * is fully cleared on login / logout.
+   *
+   * **Idempotency / Side effects**: safe. Read-only.
+   *
+   * **UI guidance**: see [UI Guide — `getMiniGames`](../../docs/ui/minigames/UIGuide_getMiniGames.md).
+   *
+   * **Visitor mode**: supported. Only templates configured with
+   * `is_visitor_mode = true` in the BO are returned for anonymous
+   * sessions. Spins from these templates may also be played (visitor
+   * mode is the one mini-game flow that does support play — see
+   * {@link playMiniGame} for the visitor-stop semantics).
+   *
+   * @param params              Optional. Omit to fetch without subscribing.
+   * @param params.onUpdate     Callback invoked with the full refreshed
+   *                            template array after any spin-count
+   *                            change, spin response, or acknowledge
+   *                            response on this connection.
+   * @returns                   Promise resolving to the template
+   *                            array. Empty if no templates are
+   *                            visible to the user.
+   *
+   * @example
+   * ```ts
+   * const games = await window._smartico.api.getMiniGames({
+   *   onUpdate: (refreshed) => {
+   *     console.log('[smartico] mini-game templates refreshed — re-render lobby from this array:', refreshed);
+   *   },
    * });
-   * ```
    *
+   * // Filter the lobby view per the visibility flag.
+   * const visible = games.filter(g =>
+   *   !g.visibile_when_can_spin || (g.spin_count && g.spin_count > 0)
+   * );
+   *
+   * for (const g of visible) {
+   *   console.log('[smartico] render game card', g.id, '—', g.name,
+   *     '— type:', g.saw_game_type,
+   *     '— buy-in:', g.saw_buyin_type,
+   *     '— spins available:', g.spin_count ?? 0,
+   *     '— jackpot:', g.jackpot_current, g.jackpot_symbol);
+   * }
+   * ```
    */
   async getMiniGames({
     onUpdate
@@ -5374,19 +6710,73 @@ class WSAPIMiniGames extends WSAPIRaffles {
     return OCache.use(onUpdateContextKey.Saw, ECacheContext.WSAPI, () => this.api.sawGetTemplatesT(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.
+   * Returns a paginated, newest-first list of the user's past
+   * mini-game spins — each row carries the won prize ID, the
+   * client-side `request_id` used for the spin, and a
+   * server-recorded `is_claimed` flag (`true` if the spin has been
+   * acknowledged). Optionally filter to a single template via
+   * `saw_template_id`.
+   *
+   * Use this to power a "My prizes" / win-history surface, or to
+   * recover unacknowledged spins (rows with `is_claimed === false`
+   * carry a `client_request_id` you can pass to
+   * {@link miniGameWinAcknowledgeRequest}).
    *
-   * **Example**:
-   * ```
-   * _smartico.api.getMiniGamesHistory().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * @remarks
+   * **Pagination**
+   * `limit` defaults to 20, `offset` defaults to 0. Sort order is
+   * `create_date` DESC (newest first) — no client-side re-sort
+   * required. For "load more" pagination, advance `offset` by the
+   * page size on each subsequent call.
+   *
+   * The underlying protocol carries a `hasMore` boolean on the
+   * response, but the SDK strips it from the public surface —
+   * detect end of list when the returned array length is less than
+   * `limit`.
+   *
+   * **`is_claimed` semantics**
+   * Maps directly to the server's "acknowledge_date is non-null"
+   * state. A spin where the auto-acknowledge fire-and-forget
+   * succeeded shows `is_claimed: true`; a spin where the
+   * acknowledge was lost (network drop) or where the user is on an
+   * explicit-acknowledge flow shows `is_claimed: false` with a
+   * usable `client_request_id`. A server-side fallback job
+   * auto-acknowledges stale rows every ~60 seconds — so even
+   * "lost" prizes are eventually delivered without consumer action.
+   *
+   * **Cache TTL**: the SDK caches the response for 30 seconds.
+   * Cache is invalidated implicitly when a new spin or acknowledge
+   * response lands.
+   *
+   * **Idempotency / Side effects**: safe. Read-only.
+   *
+   * **UI guidance**: see [UI Guide — `getMiniGamesHistory`](../../docs/ui/minigames/UIGuide_getMiniGamesHistory.md).
    *
-   * **Visitor mode: not supported**
+   * **Visitor mode**: not supported.
+   *
+   * @param params                  Optional pagination + filter bag.
+   * @param params.limit            Page size. Defaults to 20.
+   * @param params.offset           Number of rows to skip. Defaults to 0.
+   * @param params.saw_template_id  When set, scopes the history to
+   *                                a single template's spins.
+   *
+   * @returns Promise resolving to `TSawHistory[]` in newest-first
+   *          order. Empty when the user has no history.
+   *
+   * @example
+   * ```ts
+   * const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
+   *
+   * // Show unacknowledged spins with a Claim CTA.
+   * const unacknowledged = history.filter(h => !h.is_claimed);
+   * console.log('[smartico] surface a "Claim" CTA on these', unacknowledged.length, 'history rows:',
+   *   unacknowledged.map(h => h.client_request_id));
+   *
+   * // Load-more pagination — advance offset by the prior page size.
+   * const page2 = await window._smartico.api.getMiniGamesHistory({ limit: 20, offset: 20 });
+   * console.log('[smartico] page 2 loaded —', page2.length, 'more rows;',
+   *   page2.length < 20 ? 'end of list reached, hide "Load more"' : 'keep "Load more" visible');
+   * ```
    */
   async getMiniGamesHistory({
     limit,
@@ -5396,18 +6786,164 @@ class WSAPIMiniGames extends WSAPIRaffles {
     return OCache.use(onUpdateContextKey.SAWHistory, ECacheContext.WSAPI, () => this.api.getSawWinningHistoryT(this.userExtId, limit, offset, saw_template_id), CACHE_DATA_SEC);
   }
   /**
-   * 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.
+   * Plays one round of a mini-game template — runs the server's
+   * randomised prize selection, deducts the buy-in cost (if any),
+   * and returns the won `prize_id`. After the play resolves, the SDK
+   * automatically fires a server-side acknowledgement on a
+   * fire-and-forget basis, marking the spin as "delivered" so the
+   * prize takes effect.
+   *
+   * Works for all `SAWGameType` values EXCEPT:
+   * - `PrizeDrop` — prizes arrive server-pushed; do NOT call
+   *   `playMiniGame` for this type.
+   * - `MatchX` / `Quiz` — prediction submission goes through a
+   *   separate games server; `playMiniGame` is not the entry point.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.playMiniGame(55).then((result) => {
-   *      console.log(result);
+   * @remarks
+   * **Preconditions**
+   * Read the candidate template from {@link getMiniGames} and check:
+   * - `spin_count > 0` for spin-based templates
+   *   (`saw_buyin_type === 'spins'`).
+   * - Sufficient balance for paid templates — points / gems /
+   *   diamonds from {@link getUserProfile} against
+   *   `buyin_cost_points` / `_gems` / `_diamonds`.
+   * - `next_available_spin_ts` is in the past (or unset) — the
+   *   server enforces a per-period max-attempts cap.
+   * - Template is currently in its active period
+   *   (operator-configured `activeFromDate` / `activeTillDate`).
+   *
+   * **Error codes** (in `err_code`, typed as {@link SAWSpinErrorCode})
+   * - `0` (`SAW_OK`) — success; `prize_id` identifies the won prize
+   *   in `template.prizes`.
+   * - `40001` (`SAW_NO_SPINS`) — user has no spin attempts for a
+   *   spin-based template.
+   * - `40002` (`SAW_PRIZE_POOL_EMPTY`) — all prize slots in the
+   *   template are depleted.
+   * - `40003` (`SAW_NOT_ENOUGH_POINTS`) — insufficient points for a
+   *   points-cost template.
+   * - `40004` (`SAW_FAILED_MAX_SPINS_REACHED`) — per-period
+   *   max-attempts cap reached. The server's
+   *   `first_spin_in_period` value (exposed in
+   *   {@link TMiniGamePlayBatchResult}; not surfaced in the single
+   *   `TMiniGamePlayResult`) marks the period start.
+   * - `40007` (`SAW_TEMPLATE_NOT_ACTIVE`) — template outside its
+   *   active time window.
+   * - `40009` (`SAW_NOT_IN_SEGMENT`) — user fails the template's
+   *   visibility segment check, OR (for lootbox variants) the day's
+   *   prize pool is empty.
+   * - `40011` (`SAW_NO_BALANCE_GEMS`) — insufficient gems.
+   * - `40012` (`SAW_NO_BALANCE_DIAMONDS`) — insufficient diamonds.
+   * - `-40001` (`SAW_VISITOR_STOP_SPIN_REQUEST`) — visitor session
+   *   tried to play a non-visitor-mode template. The default UI
+   *   silently stops the game; no prize awarded.
+   * - other non-zero — generic server error. Surface `err_message`.
+   *
+   * **Prize handling**
+   * On `err_code === 0`, `prize_id` matches an entry in
+   * `template.prizes`. Look up the prize's `prize_type`
+   * ({@link MiniGamePrizeTypeName}) to decide UI treatment:
+   * - `'no-prize'` — the user spun but won nothing (an operator-
+   *   configured "loss" slot). Buy-in is still deducted.
+   * - `'points'` / `'gems-and-diamonds'` / `'spin'` — value
+   *   credited to the user's profile / spin balance; visible on
+   *   the next refresh.
+   * - `'bonus'` — surfaces via {@link getBonuses}.
+   * - `'jackpot'` — drains the template's `jackpot_current` to the
+   *   user; resets the accumulator.
+   * - `'raffle-ticket'` — adds tickets to the relevant raffle.
+   * - `'mission'` / `'change-level'` — visible via the
+   *   corresponding domain methods.
+   * - `'manual'` — operator delivers offline.
+   *
+   * **Auto-acknowledge**
+   * The SDK calls the server's acknowledge endpoint immediately
+   * after the spin response, on a fire-and-forget basis (not
+   * awaited). This marks the spin as "delivered" so prize effects
+   * take hold. If the auto-acknowledge fails (network drop), the
+   * spin appears as `is_claimed: false` in
+   * {@link getMiniGamesHistory}; the consumer can recover it by
+   * passing the `client_request_id` to
+   * {@link miniGameWinAcknowledgeRequest}. A server-side fallback
+   * job auto-acknowledges stale spins every ~60 seconds, so prizes
+   * are eventually delivered even without consumer action.
+   *
+   * **Idempotency**: NOT idempotent. A double-click sends two
+   * spins and deducts the buy-in twice. The SDK does NOT guard
+   * against rapid clicks at the public API level — guard the call
+   * site with an in-flight flag. The server enforces a per-user
+   * per-template lock that serialises concurrent requests, so two
+   * simultaneous calls won't be processed in parallel, but they
+   * will both be processed sequentially (i.e. both deduct).
+   *
+   * **Refresh after success (and after failure)**
+   * The SDK automatically refreshes the templates cache on every
+   * spin response and fires any `onUpdate` callback registered via
+   * {@link getMiniGames} or this method. After `err_code === 0`, the
+   * affected template's `spin_count` / `jackpot_current` /
+   * `next_available_spin_ts` reflect the new state on the
+   * refreshed array.
+   *
+   * **Side effects** (on `err_code === 0`)
+   * - Buy-in deducted from the user's balance (points / gems /
+   *   diamonds / spin tickets — depending on `saw_buyin_type`).
+   *   Balance updates flow via the user-properties channel
+   *   (subscribe to {@link getUserProfile} `props_change` to
+   *   observe).
+   * - Prize value credited per the prize's type (see "Prize
+   *   handling" above).
+   * - A `minigame_attempt` analytics event fires server-side with
+   *   the result status.
+   *
+   * **UI guidance**: see [UI Guide — `playMiniGame`](../../docs/ui/minigames/UIGuide_playMiniGame.md).
+   *
+   * **Visitor mode**: not supported. Visitor sessions trying to
+   * spin receive `SAW_VISITOR_STOP_SPIN_REQUEST (-40001)`.
+   *
+   * @param template_id  The mini-game template ID (from
+   *                     `TMiniGameTemplate.id`).
+   * @param params       Optional. Pass an `onUpdate` callback to
+   *                     subscribe to subsequent template refreshes.
+   * @returns `{ err_code, err_message, prize_id }` — success when
+   *          `err_code === 0`. `prize_id` is always populated; look
+   *          it up in `template.prizes` to interpret the prize.
+   *
+   * @example
+   * ```ts
+   * const games = await window._smartico.api.getMiniGames({
+   *   onUpdate: (refreshed) => console.log('[smartico] templates refreshed — re-render lobby', refreshed),
    * });
-   * ```
+   * const game = games.find(g => g.id === templateId);
    *
-   * **Visitor mode: not supported**
+   * if (!game) {
+   *   console.log('[smartico] template not in current list — refresh getMiniGames');
+   *   return;
+   * }
+   * if (game.saw_buyin_type === 'spins' && (game.spin_count ?? 0) === 0) {
+   *   console.log('[smartico] no spins available — disable Play button, show "No spins" message');
+   *   return;
+   * }
+   *
+   * console.log('[smartico] play starting — set in-flight flag, start game animation (wheel spin / scratch / lootbox open / etc.)');
+   * const r = await window._smartico.api.playMiniGame(game.id);
+   * console.log('[smartico] play response received');
+   *
+   * if (r.err_code === 0) {
+   *   const prize = game.prizes.find(p => p.id === r.prize_id);
+   *   if (prize?.prize_type === 'no-prize') {
+   *     console.log('[smartico] user lost — animate to the no-prize slot and show "Better luck next time" modal');
+   *   } else {
+   *     console.log('[smartico] user won — animate to prize', prize?.name,
+   *       '— show acknowledge modal per template.acknowledge_type;',
+   *       'getMiniGames onUpdate fires shortly with refreshed spin_count / jackpot');
+   *   }
+   * } else if (r.err_code === 40004) {
+   *   console.error('[smartico] max spins reached — show countdown to next available spin (use playMiniGameBatch for first_spin_in_period if needed)');
+   * } else if (r.err_code === -40001) {
+   *   console.log('[smartico] visitor stopped — silently end the game, no prize modal');
+   * } else {
+   *   console.error('[smartico] play failed — show generic error with this message:', r.err_message);
+   * }
+   * ```
    */
   async playMiniGame(template_id, {
     onUpdate
@@ -5425,29 +6961,171 @@ class WSAPIMiniGames extends WSAPIRaffles {
     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);
-   * });
+   * Manually acknowledges a mini-game spin — marks the spin as
+   * "delivered" so the prize takes effect server-side. Most consumers
+   * do NOT need to call this method directly; {@link playMiniGame}
+   * and {@link playMiniGameBatch} auto-acknowledge on success. Use
+   * this only for recovery scenarios.
+   *
+   * @remarks
+   * **When to call**
+   * - **Lost auto-acknowledge** — when the WebSocket dropped between
+   *   the spin response and the auto-acknowledge fire-and-forget,
+   *   the spin shows `is_claimed: false` in
+   *   {@link getMiniGamesHistory}. Pass that row's
+   *   `client_request_id` here to deliver the prize.
+   * - **Explicit-acknowledge UI** — for templates configured with
+   *   the `ExplicitAcknowledge` acknowledge type (operator
+   *   decision), the consumer's UI shows a "Claim" CTA after the
+   *   prize animation. Click handler calls this method with the
+   *   spin's `client_request_id` rather than auto-acknowledging.
+   *
+   * **No-op on already-acknowledged spins**
+   * The server's acknowledge SQL matches on `acknowledge_date IS
+   * NULL` — a duplicate call returns successfully with no effect.
+   *
+   * **Server-side fallback**
+   * Even without ever calling this method, a server-side job
+   * auto-acknowledges stale spins every ~60 seconds — so prizes are
+   * eventually delivered. The `is_claimed` flag flips on the next
+   * `getMiniGamesHistory` call after the job runs.
+   *
+   * **Idempotency**: safe. Repeated calls have no effect after the
+   * first.
+   *
+   * **Side effects** (on first successful call for an unacknowledged
+   * spin)
+   * - Prize value credited per the prize's type (see
+   *   {@link playMiniGame} "Prize handling").
+   * - The spin's `is_claimed` flag flips to `true` on the next
+   *   {@link getMiniGamesHistory} call.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param request_id  The `client_request_id` from a `TSawHistory`
+   *                    row returned by {@link getMiniGamesHistory}.
+   *
+   * @example
+   * ```ts
+   * const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
+   * const unacknowledged = history.filter(h => !h.is_claimed);
+   *
+   * for (const row of unacknowledged) {
+   *   console.log('[smartico] re-acknowledging stale spin', row.client_request_id);
+   *   await window._smartico.api.miniGameWinAcknowledgeRequest(row.client_request_id);
+   * }
+   *
+   * // Re-fetch history to see the updated is_claimed flags.
+   * const fresh = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
+   * console.log('[smartico] history after recovery —', fresh.filter(h => !h.is_claimed).length, 'still unacknowledged');
    * ```
    */
   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.
+   * Plays a mini-game template `spin_count` times in one round-trip.
+   * Returns an array of per-spin results — each independent, each
+   * with its own error code. Like {@link playMiniGame}, the SDK
+   * auto-acknowledges every result on a fire-and-forget basis.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.playMiniGameBatch(55, 10).then((result) => {
-   *      console.log(result);
-   * });
+   * Use this when a UI offers "spin N times" affordances
+   * (multi-spin buttons, lootbox open-N flows). The server processes
+   * each spin independently — there is no atomicity / rollback if
+   * one fails.
+   *
+   * @remarks
+   * **Result shape note** — `TMiniGamePlayBatchResult` uses
+   * `errCode` / `errMessage` (camelCase) — DIFFERENT from
+   * {@link TMiniGamePlayResult} which uses `err_code` / `err_message`
+   * (snake_case). Branch on the camelCase keys when reading batch
+   * results.
+   *
+   * **Per-spin independence**
+   * The server iterates the requested spins and calls the prize
+   * engine once per entry. If spin #2 fails with `SAW_NO_SPINS`,
+   * spin #3 is still attempted — the server does NOT stop on first
+   * error and does NOT roll back successful spins. Each
+   * `results[i].errCode` is independent.
+   *
+   * Practical implication: if the user has 3 spins available and
+   * requests 5, expect results 0-2 with `errCode === 0` and results
+   * 3-4 with `errCode === SAW_NO_SPINS`.
+   *
+   * **Error codes**
+   * Per-result `errCode` is from {@link SAWSpinErrorCode}. See
+   * {@link playMiniGame} for the full table; the same codes apply
+   * per spin.
+   *
+   * **`first_spin_in_period` field**
+   * Populated on results where `errCode === SAW_FAILED_MAX_SPINS_REACHED`
+   * (40004). The value is the epoch-ms timestamp of the user's
+   * first spin in the current cooldown period. Compute the
+   * countdown as:
+   * `template.max_spins_period_ms - (Date.now() - first_spin_in_period)`.
+   *
+   * **`jackpot_amount` field**
+   * Populated on results where the won prize is a jackpot
+   * (`prize_type === 'jackpot'`). The amount the user just claimed
+   * from the template's jackpot accumulator.
+   *
+   * **Auto-acknowledge**
+   * The SDK fires a batch-acknowledge for all `request_id`s after
+   * the batch response lands — fire-and-forget. Same recovery
+   * semantics as {@link playMiniGame}: lost acknowledgements
+   * become recoverable via {@link miniGameWinAcknowledgeRequest}
+   * per row, and a server-side fallback job auto-acknowledges
+   * stale spins every ~60 seconds.
+   *
+   * **Idempotency**: NOT idempotent. A double-click sends two
+   * batches. Guard the call site with an in-flight flag.
+   *
+   * **Refresh after success (and after failure)**
+   * Same as {@link playMiniGame} — the templates cache refreshes
+   * and any `onUpdate` callback registered via {@link getMiniGames}
+   * fires with the updated `spin_count` / `jackpot_current`.
+   *
+   * **Side effects** (per-spin, on `errCode === 0`)
+   * Same as {@link playMiniGame} — buy-in deducted, prize value
+   * credited per prize type.
+   *
+   * **UI guidance**: see [UI Guide — `playMiniGameBatch`](../../docs/ui/minigames/UIGuide_playMiniGameBatch.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param template_id  The mini-game template ID.
+   * @param spin_count   Number of spins to play. The server attempts
+   *                     all `spin_count` spins — partial successes
+   *                     are normal when the user runs out of
+   *                     balance / spins mid-batch.
+   * @param params       Optional. Pass an `onUpdate` callback to
+   *                     subscribe to subsequent template refreshes.
+   * @returns `TMiniGamePlayBatchResult[]` — one entry per requested
+   *          spin, in request order. Note the camelCase `errCode` /
+   *          `errMessage` keys (see "Result shape note" above).
+   *
+   * @example
+   * ```ts
+   * const game = (await window._smartico.api.getMiniGames()).find(g => g.id === templateId);
+   * if (!game) return;
+   *
+   * console.log('[smartico] batch play starting — set in-flight flag, animate the chosen N spins sequentially in UI');
+   * const results = await window._smartico.api.playMiniGameBatch(game.id, 5);
+   * console.log('[smartico] batch response received — clear in-flight flag');
+   *
+   * for (const [i, r] of results.entries()) {
+   *   if (r.errCode === 0) {
+   *     const prize = game.prizes.find(p => p.id === r.saw_prize_id);
+   *     console.log('[smartico] spin', i, 'won:', prize?.name,
+   *       r.jackpot_amount ? '(jackpot: ' + r.jackpot_amount + ')' : '');
+   *   } else if (r.errCode === 40004) {
+   *     const msTillNext = game.max_spins_period_ms! - (Date.now() - (r.first_spin_in_period ?? 0));
+   *     console.log('[smartico] spin', i, 'capped — ' + Math.ceil(msTillNext / 1000) + ' s until next allowed');
+   *   } else {
+   *     console.error('[smartico] spin', i, 'failed —', r.errCode, r.errMessage);
+   *   }
+   * }
    * ```
-   * **Visitor mode: not supported**
    */
   async playMiniGameBatch(template_id, spin_count, {
     onUpdate
@@ -5482,79 +7160,297 @@ class WSAPIMiniGames extends WSAPIRaffles {
 /** @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.
+   * Returns the avatar catalog available to the current user — every pre-defined
+   * avatar configured for the label, with per-user unlock flags (`is_given`, `is_in_use`)
+   * applied server-side.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.getAvatarsList().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * The returned `avatar_url` is the absolute CDN URL (the SDK prefixes relative paths
+   * with the configured avatar domain). AI-customized variants are NOT returned here —
+   * those live in {@link getAvatarsCustomized}.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode is not supported.
+   * - No other prerequisite calls.
+   *
+   * **Visibility filter** (consumer-applied)
+   * Avatars with `hide_until_achieved === true && is_given === false` should be filtered
+   * out of the grid — they represent surprise unlocks that should remain hidden until
+   * the user earns them. The default Smartico UI drops these before rendering.
+   *
+   * **Lock state** (consumer-applied)
+   * Lock condition: `!is_given && avatar_source_type_id !== 0`. Free avatars
+   * (`avatar_source_type_id === 0`) are always selectable; non-free avatars are locked
+   * until `is_given` flips to true (operator grants via campaign, mission reward, store
+   * purchase, etc.).
+   *
+   * **Sort order**
+   * Server does NOT pre-sort. Caller must sort by `priority` ascending (lower = first).
+   *
+   * **Refresh**
+   * - The SDK caches results for 30 seconds.
+   * - {@link setAvatar} clears this cache on completion; the next call re-fetches.
+   * - No push subscription — there is no `onUpdate` callback for avatar methods.
+   * - When `is_given` flips server-side (e.g. the user earns a new avatar), the change
+   *   surfaces only on the next call after the 30-second cache window expires.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `getAvatarsList`](../../docs/ui/avatars/UIGuide_getAvatarsList.md).
+   *
+   * @returns Array of {@link TAvatarDefinition} — empty array if the feature is disabled
+   * on the label.
+   *
+   * @example
+   * ```ts
+   * const avatars = await window._smartico.api.getAvatarsList();
+   *
+   * // Apply the standard visibility filter and sort.
+   * const visible = avatars
+   *     .filter((a) => !a.hide_until_achieved || a.is_given)
+   *     .sort((a, b) => a.priority - b.priority);
+   *
+   * console.log('[smartico] visible avatars:', visible.length, '— render as a grid');
+   *
+   * const active = visible.find((a) => a.is_in_use);
+   * if (active) {
+   *     console.log('[smartico] currently in use — overlay a checkmark on this card:', active.avatar_real_id);
+   * }
+   * ```
    */
   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.
+   * Returns the user's previously generated AI-customized avatar variants.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.getAvatarsCustomized().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * Each entry is one AI-generated image derived from a base avatar in the catalog
+   * (the base is identified by `avatar_real_id` and was originally a
+   * {@link TAvatarDefinition} from {@link getAvatarsList}). These variants are stored
+   * server-side under the user record and persist across sessions.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode is not supported.
+   * - Has meaning only after at least one successful AI customization run (see below).
+   *   New users get an empty array.
+   *
+   * **Where customized avatars come from**
+   * AI customization is **not** a WebSocket method on this SDK. It is a separate HTTP
+   * POST to the operator-configured `avatar-customize` endpoint that takes a base avatar
+   * plus a style prompt from {@link getAvatarPrompts} and returns a generated CDN URL.
+   * Once that POST resolves successfully, the new variant is persisted and surfaces in
+   * the next `getAvatarsCustomized()` call. The variant URL can then be passed to
+   * {@link setAvatar} to activate it.
+   *
+   * **Relation to `getAvatarsList`**
+   * AI variants do NOT appear in {@link getAvatarsList}. Catalog and variants are two
+   * separate collections — combine them client-side if the UI needs a unified view per
+   * base avatar.
+   *
+   * **Sort order**
+   * Server does NOT pre-sort. Caller typically sorts by `dt_created` descending to show
+   * the newest variant first.
+   *
+   * **Refresh**
+   * - The SDK caches results for 30 seconds.
+   * - {@link setAvatar} clears this cache on completion.
+   * - After a successful AI customization POST, the consumer should re-call to surface
+   *   the new variant — the customization endpoint is outside the SDK so the SDK cannot
+   *   auto-invalidate.
+   * - No push subscription.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `getAvatarsCustomized`](../../docs/ui/avatars/UIGuide_getAvatarsCustomized.md).
+   *
+   * @returns Array of {@link TAvatarCustomized} — empty if the user has never run AI
+   * customization, or if the feature is disabled on the label.
+   *
+   * @example
+   * ```ts
+   * const variants = await window._smartico.api.getAvatarsCustomized();
+   *
+   * // Group by the base avatar so the UI can show "this base has 3 AI variants".
+   * const byBase = new Map<number, typeof variants>();
+   * for (const v of variants) {
+   *     const list = byBase.get(v.avatar_real_id) ?? [];
+   *     list.push(v);
+   *     byBase.set(v.avatar_real_id, list);
+   * }
+   *
+   * // Newest-first within each base.
+   * for (const list of byBase.values()) {
+   *     list.sort((a, b) => b.dt_created.localeCompare(a.dt_created));
+   * }
+   *
+   * console.log('[smartico] AI variants by base avatar — render as a carousel under each base');
+   * ```
    */
   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.
+   * Returns the catalog of AI style prompts available for avatar customization.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.getAvatarPrompts().then((result) => {
-   *      console.log(result);
-   * });
-   * ```
+   * Each entry is a "style" the user can apply to a base avatar (e.g. "Cartoon",
+   * "Watercolor", "Cyberpunk"). Prompts carry a cost expressed in points, gems, or
+   * diamonds — applying a prompt deducts the cost server-side as part of the AI
+   * generation request.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode is not supported.
+   * - No other prerequisite calls. The customization UI typically calls this on demand
+   *   when the user opens the style picker, not on app boot.
+   *
+   * **Cost handling**
+   * Each prompt declares `cost_currency_type_id` (0 = points, 1 = gems, 2 = diamonds)
+   * and `cost_value` (amount). The deduction happens server-side inside the
+   * `avatar-customize` HTTP POST (the AI generation request, which is NOT part of this
+   * SDK). The client should compare `cost_value` against the live balance from
+   * {@link getUserProfile} to disable prompts the user cannot afford, but the server is
+   * the source of truth and will reject under-funded requests authoritatively.
+   *
+   * **Refresh**
+   * - The SDK caches results for 30 seconds.
+   * - Not invalidated by {@link setAvatar} (prompts are catalog metadata, independent
+   *   of the user's active avatar).
+   * - No push subscription.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `getAvatarPrompts`](../../docs/ui/avatars/UIGuide_getAvatarPrompts.md).
+   *
+   * @returns Array of {@link TAvatarPrompt} — empty if the AI customization feature is
+   * disabled on the label.
+   *
+   * @example
+   * ```ts
+   * const [prompts, profile] = await Promise.all([
+   *     window._smartico.api.getAvatarPrompts(),
+   *     window._smartico.api.getUserProfile(),
+   * ]);
+   *
+   * for (const p of prompts) {
+   *     // The consumer reads the matching balance from profile based on
+   *     // p.cost_currency_type_id (0=points, 1=gems, 2=diamonds).
+   *     console.log('[smartico] prompt', p.name, '— cost', p.cost_value, 'currency_type', p.cost_currency_type_id);
+   * }
+   * ```
    */
   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`.
+   * Activates the specified avatar for the current user. The chosen image becomes the
+   * profile avatar — any subsequent {@link getUserProfile} call will reflect the new
+   * `avatar_url`.
    *
-   * **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);
-   *          });
-   *      }
+   * Pass `avatar_url` (a {@link TAvatarDefinition.url} from the catalog or a
+   * {@link TAvatarCustomized.url} from the AI-variant list) plus `avatar_real_id` of the
+   * base avatar. The server validates ownership before applying — locked avatars are
+   * rejected.
+   *
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode is not supported.
+   * - `avatar_url` must be non-empty and `avatar_real_id` must be truthy — the SDK
+   *   throws synchronously otherwise (the request never reaches the server).
+   * - The avatar must exist in the catalog from {@link getAvatarsList} (or be an AI
+   *   variant of a base avatar the user already owns). Free avatars
+   *   (`avatar_source_type_id === 0`) and the user's currently active avatar bypass the
+   *   ownership check; all others require `is_given === true`.
+   *
+   * **Error codes** (in `err_code`)
+   * - `0` — success; cache is cleared and the profile avatar updates immediately.
+   * - `1` — avatar not found in the catalog. The `avatar_real_id` doesn't exist for
+   *   this label.
+   * - `2` — avatar inactive (deactivated by the operator).
+   * - `3` — outside the avatar's active time window
+   *   (`active_from_date` / `active_till_date`).
+   * - `4` — user does not own this avatar (it isn't in their `is_given` set and isn't
+   *   a free / default avatar).
+   * - other non-zero — generic server error; surface `err_message` if present.
+   *
+   * The default Smartico UI shows a hardcoded "Failed to apply avatar" toast on any
+   * non-zero `err_code` and does not surface `err_message`. Custom UIs SHOULD branch
+   * on the code and prefer `err_message` when present (it is the localized server
+   * string).
+   *
+   * **Refresh after success**
+   * - The SDK clears both the `getAvatarsList` and `getAvatarsCustomized` caches —
+   *   the next call to either returns fresh data with the new `is_in_use` flag set on
+   *   the chosen avatar.
+   * - The server persists the new avatar URL on the user record; {@link getUserProfile}
+   *   reflects it on the next read in this session.
+   * - **No push to other open sessions.** A second device / tab the user is logged in
+   *   on will not see the new avatar until it next calls {@link getUserProfile} or
+   *   re-identifies. Plan UI accordingly.
+   *
+   * **Idempotency**: safe to retry. Re-applying the same `avatar_real_id` returns
+   * `err_code: 0` and produces no double side effects (no double-deduction — this
+   * method does not charge any currency — and no duplicate log entries).
+   *
+   * **Side effects**: updates the user's stored `avatar_id` / `avatar_real_id`. Does
+   * NOT cost points, gems, or diamonds — the cost lives on the separate AI
+   * customization HTTP flow ({@link getAvatarPrompts}). Does NOT write a user-visible
+   * entry to {@link getActivityLog}.
+   *
+   * **UI guidance**: see [UI Guide — `setAvatar`](../../docs/ui/avatars/UIGuide_setAvatar.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param props.avatar_url       Absolute CDN URL of the avatar image. Read from
+   *                                {@link TAvatarDefinition.url} for catalog avatars or
+   *                                {@link TAvatarCustomized.url} for AI variants.
+   * @param props.avatar_real_id   Numeric ID of the base avatar from
+   *                                {@link TAvatarDefinition.avatar_real_id}. For AI
+   *                                variants, this is the `avatar_real_id` of the base
+   *                                they were derived from.
+   * @returns {@link TSetAvatarResult} — check `err_code === 0` for success.
+   *
+   * @example
+   * ```ts
+   * const avatars = await window._smartico.api.getAvatarsList();
+   * const target = avatars.find((a) => a.avatar_real_id === 7);
+   *
+   * if (!target) {
+   *     console.error('[smartico] avatar 7 not in catalog — hide the picker entry');
+   *     return;
+   * }
+   *
+   * const isLocked = !target.is_given && target.avatar_source_type_id !== 0;
+   * if (isLocked) {
+   *     console.log('[smartico] avatar is locked — show "earn this first" prompt instead of calling setAvatar');
+   *     return;
+   * }
+   *
+   * const r = await window._smartico.api.setAvatar({
+   *     avatar_url:     target.avatar_url,
+   *     avatar_real_id: target.avatar_real_id,
    * });
-   * ```
    *
-   * **Visitor mode: not supported**
+   * switch (r.err_code) {
+   *     case 0:
+   *         console.log('[smartico] avatar applied — close picker, refresh header avatar');
+   *         break;
+   *     case 1:
+   *         console.error('[smartico] avatar not in catalog — refresh catalog and show error');
+   *         break;
+   *     case 2:
+   *         console.error('[smartico] avatar inactive — operator disabled it; hide from picker');
+   *         break;
+   *     case 3:
+   *         console.error('[smartico] outside time window — show "available on X" message');
+   *         break;
+   *     case 4:
+   *         console.error('[smartico] not owned — show unlock requirements');
+   *         break;
+   *     default:
+   *         console.error('[smartico] avatar apply failed — show generic error toast:', r.err_message);
+   * }
+   * ```
    */
   async setAvatar(props) {
     var _r$errCode;
@@ -5577,37 +7473,65 @@ class WSAPIAvatars extends WSAPIMiniGames {
 /** @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.
-   *
-   * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-   *
-   * **Response** `GamesApiResponse<GamePickRound[]>`:
-   * - `errCode` - 0 on success
-   * - `data` - Array of rounds, each containing:
-   *   - `round_id`, `round_name` - Round identifier and display name
-   *   - `open_date`, `last_bet_date` - Timestamps (ms) for round open and betting deadline
-   *   - `is_active_now`, `is_resolved` - Round state flags
-   *   - `round_status_id` - Round status: -1 (active), 2 (no more bets), 3 (all events resolved), 4 (round resolved)
-   *   - `score_full_win`, `score_part_win`, `score_lost` - Scoring rules per prediction outcome
-   *   - `user_score` - Current user's total score in this round
-   *   - `user_placed_bet` - Whether the user has submitted predictions
-   *   - `has_open_for_bet_events` - Whether there are events still open for betting
-   *   - `events[]` - Array of events with `gp_event_id`, `market_type_id`, `event_meta` (team names, images, sport), `match_date`, `is_open_for_bets`, `odds_details`, and user selection fields
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.gamePickGetActiveRounds({
-   *      saw_template_id: 1083,
-   * }).then((result) => {
-   *      console.log(result.data); // GamePickRound[]
-   *      result.data.forEach(round => {
-   *          console.log(round.round_name, round.events.length);
-   *      });
-   * });
-   * ```
+   * Returns every open round for a MatchX or Quiz game template, with the full
+   * event list (matches / questions) and the current user's selections per event.
    *
-   * **Visitor mode: not supported**
+   * Use to power the rounds-lobby screen — typically a list of round cards a user
+   * can tap into to make predictions. For a single round, use
+   * {@link gamePickGetActiveRound} (lighter payload when only one round is shown).
+   *
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated.
+   * - `saw_template_id` must reference a MatchX or Quiz game template. The SDK
+   *   throws synchronously if it's missing.
+   *
+   * **Transport**
+   * Game Pick methods are HTTP REST calls to a separate Game Pick games server
+   * (not the main WebSocket). One consequence: there is no SDK cache and no push
+   * subscription — every call is a fresh server roundtrip.
+   *
+   * **Round status**
+   * Each round's `round_status_id` is a {@link GPRoundStatus} value. Rounds with
+   * status `NoEventsDefined` (1) are filtered out server-side and never appear
+   * here. Other values: `Other` (-1, normally open), `NoMoreBetsAllowed` (2),
+   * `AllEventsResolved_ButNotRound` (3), `RoundResolved` (4 — appears here only
+   * briefly during transition; use {@link gamePickGetHistory} for resolved rounds).
+   *
+   * **Error codes** (in `errCode`)
+   * - `0` — success.
+   * - `100002` — template not found (the `saw_template_id` doesn't reference a
+   *   MatchX/Quiz game).
+   * - `100003` — no open rounds available for this template right now.
+   * - `100000` — auth hash invalid; SDK session needs re-initialization.
+   * - `100004` — generic server error.
+   *
+   * **Refresh**
+   * - No cache; every call is live.
+   * - No push subscription. Poll while the user is on the screen if you need
+   *   live round-status changes (typically every 30–60 s is enough).
+   *
+   * **Visitor mode**: not supported. The SDK throws synchronously on visitor
+   * sessions.
+   *
+   * **UI guidance**: see [UI Guide — `gamePickGetActiveRounds`](../../docs/ui/gamepick/UIGuide_gamePickGetActiveRounds.md).
+   *
+   * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+   * @returns Wrapped {@link GamesApiResponse} of {@link GamePickRound} array.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.gamePickGetActiveRounds({ saw_template_id: 1083 });
+   *
+   * if (r.errCode !== 0) {
+   *     console.error('[smartico] active rounds fetch failed — show empty rounds lobby:', r.errMessage);
+   *     return;
+   * }
+   *
+   * for (const round of r.data ?? []) {
+   *     console.log('[smartico] render a round card:', round.round_name, '— events:', round.events.length, 'user has placed bet:', round.user_placed_bet);
+   * }
+   * ```
    */
   async gamePickGetActiveRounds(props) {
     if (!props.saw_template_id) {
@@ -5616,29 +7540,56 @@ class WSAPIGamePick extends WSAPIAvatars {
     return this.api.gpGetActiveRounds(props.saw_template_id);
   }
   /**
-   * Returns a single active round for the specified MatchX or Quiz game.
-   * The round includes full event details with the current user's selections.
+   * Returns a single round (events, user selections, scoring rules) for a
+   * MatchX or Quiz game. Use to power the round-detail / prediction-input
+   * screen the user lands on after picking a round from the lobby.
    *
-   * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-   * @param props.round_id - The specific round to retrieve
+   * Same shape as one entry of {@link gamePickGetActiveRounds}; cheaper when the
+   * UI only shows one round at a time.
    *
-   * **Response** `GamesApiResponse<GamePickRound>`:
-   * - `errCode` - 0 on success
-   * - `data` - Single round object with the same structure as in `gamePickGetActiveRounds`,
-   *   including `events[]` with full event details, user selections, and resolution info
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   * - `saw_template_id` and `round_id` are mandatory — the SDK throws if either
+   *   is missing.
+   *
+   * **Error codes** (in `errCode`)
+   * - `0` — success.
+   * - `4` — round / event not found (e.g. round resolved after the last
+   *   `gamePickGetActiveRounds` poll); non-fatal — retry after a fresh active-
+   *   rounds fetch.
+   * - `100002` — template not found.
+   * - `100000` — auth hash invalid.
+   * - `100004` — generic server error.
+   *
+   * **Refresh**
+   * - No cache; every call is live.
+   * - Re-call after {@link gamePickSubmitSelection} or
+   *   {@link gamePickSubmitSelectionQuiz} to surface the persisted predictions.
+   * - Poll while the user is on the prediction screen if event resolution
+   *   updates are needed (typically every 30–60 s).
    *
-   * **Example**:
-   * ```
-   * _smartico.api.gamePickGetActiveRound({
-   *      saw_template_id: 1083,
-   *      round_id: 31652,
-   * }).then((result) => {
-   *      console.log(result.data.round_name, result.data.events.length);
-   *      console.log(result.data.user_score, result.data.user_placed_bet);
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `gamePickGetActiveRound`](../../docs/ui/gamepick/UIGuide_gamePickGetActiveRound.md).
+   *
+   * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+   * @param props.round_id         ID of the round to fetch.
+   * @returns Wrapped {@link GamesApiResponse} of a single {@link GamePickRound}.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.gamePickGetActiveRound({
+   *     saw_template_id: 1083,
+   *     round_id:        31652,
    * });
-   * ```
    *
-   * **Visitor mode: not supported**
+   * if (r.errCode === 0 && r.data) {
+   *     console.log('[smartico] render round detail page —', r.data.round_name, '— user has placed bet:', r.data.user_placed_bet, 'score so far:', r.data.user_score);
+   * } else {
+   *     console.error('[smartico] round fetch failed — bounce back to the lobby and refresh:', r.errMessage);
+   * }
+   * ```
    */
   async gamePickGetActiveRound(props) {
     if (!props.saw_template_id) {
@@ -5650,29 +7601,52 @@ class WSAPIGamePick extends WSAPIAvatars {
     return this.api.gpGetActiveRound(props.saw_template_id, props.round_id);
   }
   /**
-   * Returns the history of all rounds (including resolved ones) for the specified MatchX or Quiz game.
-   * Each round contains full event details with results and the current user's predictions.
+   * Returns the full round history (active + resolved) for a MatchX or Quiz game
+   * template, newest-first. Each round carries the user's predictions plus the
+   * server-resolved outcome on each event.
    *
-   * @param props.saw_template_id - The ID of the MatchX or Quiz game template
+   * Use to power a "Past predictions" / history tab. For just the open rounds,
+   * use {@link gamePickGetActiveRounds} (faster — skips resolved data).
    *
-   * **Response** `GamesApiResponse<GamePickRound[]>`:
-   * - `errCode` - 0 on success
-   * - `data` - Array of rounds ordered by `round_row_id` descending (newest first).
-   *   Each round has the same structure as in `gamePickGetActiveRounds`, including resolved events
-   *   with `resolution_type_id` (0=None, 2=Lost, 3=PartialWin, 4=FullWin) and `resolution_score`
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.gamePickGetHistory({
-   *      saw_template_id: 1083,
-   * }).then((result) => {
-   *      result.data.forEach(round => {
-   *          console.log(round.round_name, 'Score:', round.user_score, 'Resolved:', round.is_resolved);
-   *      });
-   * });
-   * ```
+   * **Sort order**
+   * Server returns rounds newest-first. No client-side sort needed.
    *
-   * **Visitor mode: not supported**
+   * **Per-event resolution**
+   * Each event in the rounds carries `resolution_type_id` — values are from
+   * {@link GamePickResolutionType}: `None` (0, not yet resolved), `Lost` (2),
+   * `PartialWin` (3), `FullWin` (4). Use these to render result badges on
+   * each event row.
+   *
+   * **Error codes** (in `errCode`)
+   * - `0` — success.
+   * - `100002` — template not found.
+   * - `100000` — auth hash invalid.
+   * - `100004` — generic server error.
+   *
+   * **Refresh**
+   * - No cache.
+   * - No push subscription. Re-call when the user opens the history tab.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `gamePickGetHistory`](../../docs/ui/gamepick/UIGuide_gamePickGetHistory.md).
+   *
+   * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+   * @returns Wrapped {@link GamesApiResponse} of {@link GamePickRound} array,
+   * newest-first.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.gamePickGetHistory({ saw_template_id: 1083 });
+   *
+   * for (const round of r.data ?? []) {
+   *     console.log('[smartico] history row —', round.round_name, 'score:', round.user_score, 'resolved:', round.is_resolved);
+   * }
+   * ```
    */
   async gamePickGetHistory(props) {
     if (!props.saw_template_id) {
@@ -5681,36 +7655,66 @@ class WSAPIGamePick extends WSAPIAvatars {
     return this.api.gpGetGamesHistory(props.saw_template_id);
   }
   /**
-   * Returns the leaderboard for a specific round within a MatchX or Quiz game.
-   * Use `round_id = -1` (AllRoundsGameBoardID) to get the season/overall leaderboard across all rounds.
-   *
-   * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-   * @param props.round_id - The round to get the leaderboard for. Use -1 for overall/seasonal leaderboard
-   *
-   * **Response** `GamesApiResponse<GamePickRoundBoard>`:
-   * - `errCode` - 0 on success
-   * - `data` - Leaderboard object containing:
-   *   - Round base fields (`round_id`, `round_name`, `open_date`, `last_bet_date`, etc.)
-   *   - `users[]` - Ranked list of players, each with:
-   *     - `ext_user_id`, `int_user_id` - User identifiers
-   *     - `public_username`, `avatar_url` - Display info (usernames may be masked based on label settings)
-   *     - `gp_position` - Leaderboard rank (null if not yet ranked)
-   *     - `resolution_score` - Total score in this round
-   *     - `full_wins_count`, `part_wins_count`, `lost_count` - Prediction outcome counts
-   *   - `my_user` - Current user's entry (same fields as above), or null if user hasn't participated
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.gamePickGetBoard({
-   *      saw_template_id: 1083,
-   *      round_id: 31652,
-   * }).then((result) => {
-   *      console.log('Top players:', result.data.users);
-   *      console.log('My position:', result.data.my_user?.gp_position);
+   * Returns the leaderboard for a MatchX or Quiz game round — ranked list of
+   * players plus the current user's entry (`my_user`). Pass `round_id: -1` for
+   * the season / overall leaderboard across every round in the template.
+   *
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   *
+   * **`round_id` semantics**
+   * - Positive `round_id` — per-round leaderboard scoped to that round's events.
+   * - `-1` — season / overall leaderboard aggregating scores across every round
+   *   of the template.
+   *
+   * **`my_user`**
+   * The current user's entry is returned separately from the `users[]` array
+   * — `my_user` may be `null` if the user has never made a prediction on this
+   * round / template. Use it to render the user's rank in a sticky footer or
+   * "you are here" highlight regardless of pagination.
+   *
+   * **Username masking**
+   * `public_username` on other players may be masked / anonymized by operator
+   * label settings. Always pair with `avatar_url` so the user can recognize
+   * themselves in the ranking by avatar even when usernames are hidden.
+   *
+   * **Error codes** (in `errCode`)
+   * - `0` — success.
+   * - `100002` — template not found.
+   * - `100000` — auth hash invalid.
+   * - `100004` — generic server error.
+   *
+   * **Refresh**
+   * - No cache.
+   * - No push subscription. Poll while the leaderboard is visible
+   *   (every 30–60 s) if you want live rank updates after match
+   *   resolution.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `gamePickGetBoard`](../../docs/ui/gamepick/UIGuide_gamePickGetBoard.md).
+   *
+   * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+   * @param props.round_id         Round ID, or `-1` for the season leaderboard.
+   * @returns Wrapped {@link GamesApiResponse} of {@link GamePickRoundBoard}.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.gamePickGetBoard({
+   *     saw_template_id: 1083,
+   *     round_id:        -1, // season leaderboard
    * });
-   * ```
    *
-   * **Visitor mode: not supported**
+   * if (r.errCode === 0 && r.data) {
+   *     console.log('[smartico] render leaderboard rows for top', r.data.users.length, 'players');
+   *     if (r.data.my_user) {
+   *         console.log('[smartico] pin "you are rank #' + r.data.my_user.gp_position + '" footer to bottom');
+   *     } else {
+   *         console.log('[smartico] user not ranked — render "Play a round to join the leaderboard" CTA');
+   *     }
+   * }
+   * ```
    */
   async gamePickGetBoard(props) {
     if (!props.saw_template_id) {
@@ -5722,43 +7726,107 @@ class WSAPIGamePick extends WSAPIAvatars {
     return this.api.gpGetGameBoard(props.saw_template_id, props.round_id);
   }
   /**
-   * Submits score predictions for a round in a MatchX game.
-   * Sends the round object with user selections for all events at once.
-   * Each event must include `team1_user_selection` and `team2_user_selection` representing predicted scores.
-   * If the user hasn't placed bets before, one game attempt (spin) will be consumed.
-   * Predictions can be edited until each match starts (if `allow_edit_answers` is enabled on the round).
-   *
-   * @param props.saw_template_id - The ID of the MatchX game template
-   * @param props.round - Round object containing `round_id` and `events[]`. Typically obtained from `gamePickGetActiveRound`
-   *   and modified with user predictions. Each event needs: `gp_event_id`, `team1_user_selection`, `team2_user_selection`
-   *
-   * **Response** `GamesApiResponse<GamePickRound>`:
-   * - `errCode` - 0 on success. Non-zero codes indicate errors (e.g. not enough points/attempts)
-   * - `data` - Updated round with all events reflecting the submitted selections.
-   *   `user_placed_bet` will be `true`, `has_not_submitted_changes` will be `false`
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.gamePickGetActiveRound({
-   *      saw_template_id: 1190,
-   *      round_id: 38665,
-   * }).then((roundData) => {
-   *      const round = roundData.data;
-   *      round.events = round.events.map(e => ({
-   *          gp_event_id: e.gp_event_id,
-   *          team1_user_selection: 1,
-   *          team2_user_selection: 0,
-   *      }));
-   *      _smartico.api.gamePickSubmitSelection({
-   *          saw_template_id: 1190,
-   *          round: round,
-   *      }).then((result) => {
-   *          console.log(result.data.user_placed_bet); // true
-   *      });
+   * Submits all score predictions for a round in a MatchX game in one shot.
+   * Each event in the round must carry `team1_user_selection` and
+   * `team2_user_selection` (the predicted scores).
+   *
+   * On the user's FIRST submit for a round, the server charges one buy-in (one
+   * "spin" / one currency deduction based on the template's `saw_buyin_type_id`).
+   * Subsequent edits within the same round are free and only persist changed
+   * selections.
+   *
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   * - `saw_template_id` and `props.round.round_id` are mandatory — SDK throws if
+   *   either is missing.
+   * - Each event passed must include `gp_event_id` and the two
+   *   `team{1,2}_user_selection` fields. Missing events default to "no change".
+   *
+   * **Error codes** (in `errCode`)
+   * - `0` — success; the response `data` is the updated round with
+   *   `user_placed_bet === true` and `has_not_submitted_changes === false`.
+   * - `3` (`NoBetsUpdatedOnSubmit`) — submit produced no changes, OR every event
+   *   is past its `last_bet_date` deadline. The buy-in is NOT consumed; the
+   *   current round is still returned in `data`.
+   * - `4` — round / event not found; refresh state and retry.
+   * - `100002` — template not found.
+   * - `100000` — auth hash invalid.
+   * - `100004` — generic server error.
+   *
+   * Buy-in failures pass through the {@link SAWSpinErrorCode} values on first
+   * submit:
+   * - `40001` — no spins left (when `saw_buyin_type_id` is Spins).
+   * - `40003` — insufficient points.
+   * - `40004` — global max-spins cap hit.
+   * - `40007` — template outside its active date window.
+   * - `40009` — user excluded by segment rule.
+   * - `40011` — insufficient gems.
+   * - `40012` — insufficient diamonds.
+   *
+   * **Idempotency**
+   * Re-submitting identical selections returns `errCode: 3` (no changes); the
+   * buy-in is consumed exactly once per round-per-user. Re-submitting after
+   * `last_bet_date` also returns `errCode: 3` without consuming the buy-in.
+   *
+   * **Side effects**
+   * - First successful submit deducts the buy-in (Points / Gems / Diamonds /
+   *   one Spin) per `saw_buyin_type_id`.
+   * - Reports a `minigame_matchx_prediction` event to the operator's event log.
+   * - Updates the round's participant counter (`users_cnt`) and per-event
+   *   counters (`num_users`).
+   * - Score is awarded after the operator resolves the round
+   *   ({@link GPRoundStatus} = `RoundResolved`).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `gamePickSubmitSelection`](../../docs/ui/gamepick/UIGuide_gamePickSubmitSelection.md).
+   *
+   * @param props.saw_template_id  ID of the MatchX game template.
+   * @param props.round            Round object with `round_id` + `events[]`
+   *                                carrying the user's score predictions.
+   * @returns Wrapped {@link GamesApiResponse} with the updated round.
+   *
+   * @example
+   * ```ts
+   * const ar = await window._smartico.api.gamePickGetActiveRound({
+   *     saw_template_id: 1190,
+   *     round_id:        38665,
    * });
-   * ```
+   * if (ar.errCode !== 0 || !ar.data) {
+   *     console.error('[smartico] could not fetch round to submit — show error and bounce back');
+   *     return;
+   * }
    *
-   * **Visitor mode: not supported**
+   * const round = ar.data;
+   * round.events = round.events.map(e => ({
+   *     gp_event_id:          e.gp_event_id,
+   *     team1_user_selection: 1,
+   *     team2_user_selection: 0,
+   * }));
+   *
+   * const r = await window._smartico.api.gamePickSubmitSelection({
+   *     saw_template_id: 1190,
+   *     round,
+   * });
+   *
+   * switch (r.errCode) {
+   *     case 0:
+   *         console.log('[smartico] predictions saved — show confirmation, refresh leaderboard');
+   *         break;
+   *     case 3:
+   *         console.log('[smartico] nothing changed (or all events closed) — silent no-op');
+   *         break;
+   *     case 40001:
+   *     case 40003:
+   *     case 40011:
+   *     case 40012:
+   *         console.error('[smartico] insufficient balance / spins — show top-up CTA:', r.errMessage);
+   *         break;
+   *     default:
+   *         console.error('[smartico] submit failed — show generic error toast:', r.errMessage);
+   * }
+   * ```
    */
   async gamePickSubmitSelection(props) {
     var _props$round;
@@ -5771,42 +7839,83 @@ class WSAPIGamePick extends WSAPIAvatars {
     return this.api.gpSubmitSelection(props.saw_template_id, props.round, false);
   }
   /**
-   * Submits answers for a round in a Quiz game.
-   * Sends the round object with user answers for all events at once.
-   * Each event must include `user_selection` with the answer value (e.g. '1', '2', 'x', 'yes', 'no' — depending on the market type).
-   * If the user hasn't placed bets before, one game attempt (spin) will be consumed.
-   * Answers can be edited until each match starts (if `allow_edit_answers` is enabled on the round).
-   *
-   * @param props.saw_template_id - The ID of the Quiz game template
-   * @param props.round - Round object containing `round_id` and `events[]`. Typically obtained from `gamePickGetActiveRound`
-   *   and modified with user answers. Each event needs: `gp_event_id`, `user_selection`
-   *
-   * **Response** `GamesApiResponse<GamePickRound>`:
-   * - `errCode` - 0 on success. Non-zero codes indicate errors (e.g. not enough points/attempts)
-   * - `data` - Updated round with all events reflecting the submitted answers.
-   *   `user_placed_bet` will be `true`, `has_not_submitted_changes` will be `false`
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.gamePickGetActiveRound({
-   *      saw_template_id: 1183,
-   *      round_id: 37974,
-   * }).then((roundData) => {
-   *      const round = roundData.data;
-   *      round.events = round.events.map(e => ({
-   *          gp_event_id: e.gp_event_id,
-   *          user_selection: 'x',
-   *      }));
-   *      _smartico.api.gamePickSubmitSelectionQuiz({
-   *          saw_template_id: 1183,
-   *          round: round,
-   *      }).then((result) => {
-   *          console.log(result.data.user_placed_bet); // true
-   *      });
+   * Submits all quiz answers for a round in one shot. Each event in the round
+   * must carry `user_selection` (the answer value — typically `"1"` / `"2"` /
+   * `"x"` for 1×2 markets, `"yes"` / `"no"` for binary markets, or any
+   * operator-defined string for custom markets).
+   *
+   * Same first-submit buy-in behavior as {@link gamePickSubmitSelection} — one
+   * buy-in is charged on the first successful submit; subsequent edits within
+   * the same round are free.
+   *
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   * - `saw_template_id` and `props.round.round_id` are mandatory — SDK throws if
+   *   either is missing.
+   * - Each event must include `gp_event_id` and `user_selection`. Missing
+   *   events default to "no change".
+   *
+   * **Error codes** (in `errCode`)
+   * - `0` — success.
+   * - `3` (`NoBetsUpdatedOnSubmit`) — no changes, OR every event past
+   *   `last_bet_date`. Buy-in NOT consumed; current round returned in `data`.
+   * - `4` — round / event not found.
+   * - `100002` — template not found.
+   * - `100000` — auth hash invalid.
+   * - `100004` — generic server error.
+   *
+   * Buy-in failures use the same {@link SAWSpinErrorCode} pass-through values
+   * as {@link gamePickSubmitSelection} — see that method's TSDoc for the
+   * `40001` / `40003` / `40004` / `40007` / `40009` / `40011` / `40012`
+   * semantics.
+   *
+   * **Idempotency**: identical to {@link gamePickSubmitSelection} — re-submit
+   * returns `errCode: 3` and never double-charges the buy-in.
+   *
+   * **Side effects**: identical to {@link gamePickSubmitSelection}, with the
+   * reported event being `minigame_quiz_prediction` instead of
+   * `minigame_matchx_prediction`.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `gamePickSubmitSelectionQuiz`](../../docs/ui/gamepick/UIGuide_gamePickSubmitSelectionQuiz.md).
+   *
+   * @param props.saw_template_id  ID of the Quiz game template.
+   * @param props.round            Round object with `round_id` + `events[]`
+   *                                carrying the user's answer selections.
+   * @returns Wrapped {@link GamesApiResponse} with the updated round.
+   *
+   * @example
+   * ```ts
+   * const ar = await window._smartico.api.gamePickGetActiveRound({
+   *     saw_template_id: 1183,
+   *     round_id:        37974,
+   * });
+   * if (ar.errCode !== 0 || !ar.data) {
+   *     console.error('[smartico] could not fetch round to submit answers — show error');
+   *     return;
+   * }
+   *
+   * const round = ar.data;
+   * round.events = round.events.map(e => ({
+   *     gp_event_id:    e.gp_event_id,
+   *     user_selection: 'x',
+   * }));
+   *
+   * const r = await window._smartico.api.gamePickSubmitSelectionQuiz({
+   *     saw_template_id: 1183,
+   *     round,
    * });
-   * ```
    *
-   * **Visitor mode: not supported**
+   * if (r.errCode === 0) {
+   *     console.log('[smartico] quiz answers saved — show confirmation');
+   * } else if (r.errCode === 3) {
+   *     console.log('[smartico] nothing changed — silent no-op');
+   * } else {
+   *     console.error('[smartico] quiz submit failed:', r.errMessage);
+   * }
+   * ```
    */
   async gamePickSubmitSelectionQuiz(props) {
     var _props$round2;
@@ -5819,35 +7928,51 @@ class WSAPIGamePick extends WSAPIAvatars {
     return this.api.gpSubmitSelection(props.saw_template_id, props.round, true);
   }
   /**
-   * Returns the current user's profile information within the specified MatchX or Quiz game.
-   * The user record is synced from the Smartico platform into the games DB (synced every 1 minute).
-   * If the user doesn't exist in the games DB yet, it will be created automatically on first call.
-   *
-   * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-   *
-   * **Response** `GamesApiResponse<GamePickUserInfo>`:
-   * - `errCode` - 0 on success
-   * - `data`:
-   *   - `ext_user_id` - External user ID (Smartico internal numeric ID)
-   *   - `int_user_id` - Internal user ID within the games system
-   *   - `public_username` - Display name
-   *   - `avatar_url` - User's avatar image URL
-   *   - `last_wallet_sync_time` - Last time the user's balance was synced from Smartico
-   *   - `ach_points_balance` - User's current points balance
-   *   - `ach_gems_balance` - User's current gems balance
-   *   - `ach_diamonds_balance` - User's current diamonds balance
-   *   - `pubic_username_set` - Whether the user has set a custom username
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.gamePickGetUserInfo({
-   *      saw_template_id: 1083,
-   * }).then((result) => {
-   *      console.log(result.data.public_username, result.data.ach_points_balance);
-   * });
-   * ```
+   * Returns the current user's profile within the Game Pick system — display
+   * name, avatar, balances, and last wallet-sync timestamp. The Game Pick server
+   * maintains its own user record that mirrors the user's Smartico balances; the
+   * mirror is updated at most once per minute, so `last_wallet_sync_time` tells
+   * the consumer how stale the balances on the response are.
    *
-   * **Visitor mode: not supported**
+   * On the user's first call for a given game, the Game Pick server lazily
+   * provisions a user record — so this method doubles as a "register the user
+   * with this game" call.
+   *
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   *
+   * **Balance freshness**
+   * The balances returned here are the cached mirror — at most ~1 minute stale.
+   * For an up-to-the-second view of Points / Gems / Diamonds, read from
+   * {@link getUserProfile} instead. Use this method's balances only for
+   * in-Game-Pick display.
+   *
+   * **Error codes** (in `errCode`)
+   * - `0` — success.
+   * - `100002` — template not found.
+   * - `100000` — auth hash invalid.
+   * - `100004` — generic server error.
+   *
+   * **Refresh**
+   * - No cache. Server-side mirror refreshes at most every 60 s.
+   * - No push subscription.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `gamePickGetUserInfo`](../../docs/ui/gamepick/UIGuide_gamePickGetUserInfo.md).
+   *
+   * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+   * @returns Wrapped {@link GamesApiResponse} of {@link GamePickUserInfo}.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.gamePickGetUserInfo({ saw_template_id: 1083 });
+   *
+   * if (r.errCode === 0 && r.data) {
+   *     console.log('[smartico] render Game Pick header — name:', r.data.public_username, '— points:', r.data.ach_points_balance, '— synced:', r.data.last_wallet_sync_time);
+   * }
+   * ```
    */
   async gamePickGetUserInfo(props) {
     if (!props.saw_template_id) {
@@ -5856,38 +7981,56 @@ class WSAPIGamePick extends WSAPIAvatars {
     return this.api.gpGetUserInfo(props.saw_template_id);
   }
   /**
-   * Returns the game configuration and the list of all rounds for the specified MatchX or Quiz game.
-   * Includes the SAW template definition, label settings, and round metadata (without events).
-   *
-   * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-   *
-   * **Response** `GamesApiResponse<GamePickGameInfo>`:
-   * - `errCode` - 0 on success
-   * - `data`:
-   *   - `sawTemplate` - Game template configuration including:
-   *     - `saw_template_id`, `saw_game_type_id` (6 = MatchX/Quiz)
-   *     - `saw_template_ui_definition` - UI settings (name, ranking options, ask_for_username, etc.)
-   *     - `saw_buyin_type_id` - Cost type (1=Free, 2=Points, 3=Gems, 4=Diamonds, 5=Spins)
-   *     - `buyin_cost_points` - Cost per attempt
-   *     - `spin_count` - Available attempts for the current user
-   *   - `allRounds[]` - List of all rounds (metadata only, no events), each with:
-   *     - `round_id`, `round_name`, `round_description`
-   *     - `open_date`, `last_bet_date` - Timestamps (ms)
-   *     - `is_active_now`, `is_resolved`, `round_status_id`
-   *   - `labelInfo` - Label/brand configuration and settings
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.gamePickGetGameInfo({
-   *      saw_template_id: 1189,
-   * }).then((result) => {
-   *      console.log(result.data.sawTemplate.saw_template_ui_definition.name);
-   *      console.log('Rounds:', result.data.allRounds.length);
-   *      console.log('Buy-in type:', result.data.sawTemplate.saw_buyin_type_id);
-   * });
-   * ```
+   * Returns the game template configuration plus a metadata listing of every
+   * round (without events). Use to power the game's welcome / lobby screen —
+   * shows the template name, buy-in cost, the user's remaining attempts, and
+   * the full round list.
    *
-   * **Visitor mode: not supported**
+   * The `allRounds[]` here is a lightweight metadata-only view — to render
+   * predictions or leaderboards, call {@link gamePickGetActiveRound} /
+   * {@link gamePickGetActiveRounds} / {@link gamePickGetBoard} for the rounds
+   * the user actually opens.
+   *
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   *
+   * **Buy-in semantics**
+   * The `sawTemplate.saw_buyin_type_id` value determines which currency is
+   * deducted on the user's first prediction in any round:
+   * - Free — no deduction.
+   * - Points — `buyin_cost_points` deducted from the user's points balance.
+   * - Gems — deducted from the user's gems balance.
+   * - Diamonds — deducted from the user's diamonds balance.
+   * - Spins — one spin counted from `spin_count`.
+   *
+   * **Error codes** (in `errCode`)
+   * - `0` — success.
+   * - `100002` — template not found.
+   * - `100000` — auth hash invalid.
+   * - `100004` — generic server error.
+   *
+   * **Refresh**
+   * - No cache.
+   * - No push subscription. Re-call after a successful
+   *   {@link gamePickSubmitSelection} to refresh `spin_count`.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `gamePickGetGameInfo`](../../docs/ui/gamepick/UIGuide_gamePickGetGameInfo.md).
+   *
+   * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+   * @returns Wrapped {@link GamesApiResponse} of {@link GamePickGameInfo}.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.gamePickGetGameInfo({ saw_template_id: 1189 });
+   *
+   * if (r.errCode === 0 && r.data) {
+   *     console.log('[smartico] render Game Pick lobby — title:', r.data.sawTemplate.saw_template_ui_definition.name);
+   *     console.log('[smartico] rounds available:', r.data.allRounds.length, '— buy-in type:', r.data.sawTemplate.saw_buyin_type_id, 'cost:', r.data.sawTemplate.buyin_cost_points);
+   * }
+   * ```
    */
   async gamePickGetGameInfo(props) {
     if (!props.saw_template_id) {
@@ -5896,35 +8039,73 @@ class WSAPIGamePick extends WSAPIAvatars {
     return this.api.gpGetGameInfo(props.saw_template_id);
   }
   /**
-   * Returns round data with events and picks for a specific user (identified by their internal user ID).
-   * Useful for viewing another user's predictions from the leaderboard.
-   * The `int_user_id` can be obtained from the `gamePickGetBoard` response (`users[].int_user_id`).
-   *
-   * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-   * @param props.round_id - The round to get info for
-   * @param props.int_user_id - Internal user ID of the player whose predictions to view (from leaderboard data)
-   *
-   * **Response** `GamesApiResponse<GamePickRound>`:
-   * - `errCode` - 0 on success
-   * - `data` - Round object with the target user's selections.
-   *   Same structure as `gamePickGetActiveRound`, but `user_selection`/`team1_user_selection`/`team2_user_selection`
-   *   fields on events reflect the specified user's picks instead of the current user's.
-   *   Events also include `resolution_type_id` (0=None, 2=Lost, 3=PartialWin, 4=FullWin) showing how each prediction was scored
-   *
-   * **Example**:
-   * ```
-   * _smartico.api.gamePickGetRoundInfoForUser({
-   *      saw_template_id: 1083,
-   *      round_id: 31652,
-   *      int_user_id: 65653810,
-   * }).then((result) => {
-   *      result.data.events.forEach(e => {
-   *          console.log(e.event_meta.team1_name, 'vs', e.event_meta.team2_name, '→', e.user_selection);
-   *      });
+   * Returns a round with another player's predictions instead of the current
+   * user's. The target player is identified by `int_user_id` (the Game Pick
+   * system's internal user ID, obtained from {@link gamePickGetBoard}'s
+   * `users[].int_user_id`).
+   *
+   * Use to power "view this player's picks" affordances opened from leaderboard
+   * rows — community / social inspection of how a top-ranked user predicted.
+   *
+   * @remarks
+   * **Preconditions**
+   * - User must be authenticated. Visitor mode not supported.
+   * - `saw_template_id`, `round_id`, and `int_user_id` are all mandatory — SDK
+   *   throws synchronously if any is missing.
+   * - `int_user_id` must come from a leaderboard fetch in the same game
+   *   template; it is stable within a template but not portable across
+   *   templates.
+   *
+   * **Shape vs `gamePickGetActiveRound`**
+   * Same {@link GamePickRound} structure, but `user_selection` /
+   * `team1_user_selection` / `team2_user_selection` reflect the TARGET user's
+   * predictions instead of the caller's. Each event still carries its own
+   * `resolution_type_id` (see {@link GamePickResolutionType}) so the UI can
+   * render result badges per pick.
+   *
+   * **Error codes** (in `errCode`)
+   * - `0` — success.
+   * - `4` — round / event / user not found.
+   * - `100002` — template not found.
+   * - `100000` — auth hash invalid.
+   * - `100004` — generic server error.
+   *
+   * **Refresh**
+   * - No cache. Re-call when opening a different leaderboard row's
+   *   "view picks" modal.
+   * - No push subscription.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * **UI guidance**: see [UI Guide — `gamePickGetRoundInfoForUser`](../../docs/ui/gamepick/UIGuide_gamePickGetRoundInfoForUser.md).
+   *
+   * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+   * @param props.round_id         ID of the round to inspect.
+   * @param props.int_user_id      Internal user ID from
+   *                                `gamePickGetBoard.users[].int_user_id`.
+   * @returns Wrapped {@link GamesApiResponse} with the target user's
+   * {@link GamePickRound}.
+   *
+   * @example
+   * ```ts
+   * const board = await window._smartico.api.gamePickGetBoard({
+   *     saw_template_id: 1083, round_id: 31652,
    * });
-   * ```
+   * const topPlayer = board.data?.users?.[0];
+   * if (!topPlayer) return;
    *
-   * **Visitor mode: not supported**
+   * const r = await window._smartico.api.gamePickGetRoundInfoForUser({
+   *     saw_template_id: 1083,
+   *     round_id:        31652,
+   *     int_user_id:     topPlayer.int_user_id,
+   * });
+   *
+   * if (r.errCode === 0 && r.data) {
+   *     for (const ev of r.data.events) {
+   *         console.log('[smartico] render row —', ev.event_meta.team1_name, 'vs', ev.event_meta.team2_name, '— picked:', ev.user_selection, '— resolution:', ev.resolution_type_id);
+   *     }
+   * }
+   * ```
    */
   async gamePickGetRoundInfoForUser(props) {
     if (!props.saw_template_id) {
@@ -5943,21 +8124,135 @@ class WSAPIGamePick extends WSAPIAvatars {
 /** @group LeaderBoard */
 class WSAPILeaderBoard extends WSAPIGamePick {
   /**
-   * 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.
+   * Returns the operator-configured standalone leaderboard for the
+   * given period type — top-20 ranked entries, the current user's
+   * own entry (when authenticated), and the configured prize table.
+   * Use this to power a leaderboard page with daily / weekly /
+   * monthly tabs.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.getLeaderBoard(1).then((result) => {
-   *     console.log(result);
-   * });
-   * ```
+   * The leaderboard for each period type is configured separately by
+   * the operator. A label may have any combination of DAILY, WEEKLY,
+   * and MONTHLY boards configured (or none).
    *
-   * **Example in the Visitor mode**:
-   * ```
-   * _smartico.vapi('EN').getLeaderBoard(1).then((result) => {
-   *    console.log(result);
-   * });
+   * @remarks
+   * **Return value note** — the runtime may return `undefined` if no
+   * board is configured for the requested `periodType`, despite the
+   * static return type being `Promise<LeaderBoardDetailsT>`. Defend
+   * against that case in consumer code.
+   *
+   * **Preconditions**
+   * Pass a `periodType` from {@link LeaderBoardPeriodType}
+   * (`DAILY = 1`, `WEEKLY = 2`, `MONTHLY = 3`). Pass
+   * `getPreviousPeriod: true` to fetch the most-recently-ended
+   * period's snapshot (yesterday's results, last week's results,
+   * last month's results) instead of the current live period. The
+   * SDK only exposes one period back — older snapshots are not
+   * reachable through this method.
+   *
+   * **Top-20 cap**
+   * The server hard-caps `users[]` at 20 entries, ordered by
+   * `position` ASC. Position values are server-computed (DENSE_RANK
+   * over all participants); the truncation at 20 is for transport
+   * size only — `position` may exceed 20 elsewhere.
+   *
+   * **The `me` field**
+   * Always populated for authenticated users (even when they have
+   * zero points in the period). `me.position === -1` is the signal
+   * that the user is active but ranked outside the top 20 (or has no
+   * activity yet). `me` is `undefined` for visitor-mode sessions.
+   *
+   * **Rewards are points only**
+   * `rewards[].points` are gamification points credited to the user's
+   * balance when the period finalizes. The leaderboard never awards
+   * gems, diamonds, store items, or bonuses. The first element of
+   * the array is the prize for place 1, the second for place 2, and
+   * so on. The array length is the number of paid places.
+   *
+   * **Cache TTL — single shared key (known limitation)**
+   * The SDK caches the response for 30 seconds under a SINGLE shared
+   * key — calling `getLeaderBoard(DAILY)` followed by
+   * `getLeaderBoard(WEEKLY)` within the same 30 s window returns the
+   * cached DAILY result for the WEEKLY call. Same applies to
+   * switching `getPreviousPeriod`. To force a fresh fetch when
+   * switching periods or current/previous, call
+   * `_smartico.api.clearCaches()` before the second call, or simply
+   * wait out the TTL.
+   *
+   * **Period boundaries**
+   * The server finalizes each period on a server-configurable
+   * schedule: DAILY at midnight + operator-defined offset; WEEKLY
+   * at the start of Monday; MONTHLY on the 1st of each month. At
+   * finalization, the server distributes the configured `rewards[]`
+   * points to the top placeholders and resets the live board. After
+   * finalization, `getLeaderBoard(periodType, false)` returns the
+   * NEW (empty) period's board; call with
+   * `getPreviousPeriod: true` to see the just-ended standings.
+   *
+   * **Refresh model**
+   * - One-shot fetch (no subscription).
+   * - No push event refreshes the cache; finalization at the period
+   *   boundary is NOT pushed to the client.
+   * - Poll manually if the consumer needs near-live state during an
+   *   in-progress period.
+   *
+   * **Idempotency / Side effects**: safe. Read-only.
+   *
+   * **UI guidance**: see [UI Guide — `getLeaderBoard`](../../docs/ui/leaderboard/UIGuide_getLeaderBoard.md).
+   *
+   * **Visitor mode**: supported. The same shape is returned, scoped
+   * to the brand's public leaderboard. `me` is `undefined` for
+   * visitors.
+   *
+   * @param periodType         The board's period type
+   *                           ({@link LeaderBoardPeriodType}).
+   *                           Selects which pre-configured board to
+   *                           fetch; the board itself is bound to one
+   *                           period by the operator.
+   * @param getPreviousPeriod  When `true`, returns the most recent
+   *                           finalized snapshot for that period type
+   *                           (e.g. last week's results). Defaults to
+   *                           `false` (current in-progress period).
+   * @returns                  Promise resolving to `LeaderBoardDetailsT`.
+   *                           **At runtime, may resolve to `undefined`**
+   *                           when no board is configured for the
+   *                           requested period type — guard against it.
+   *
+   * @example
+   * ```ts
+   * import { LeaderBoardPeriodType } from '@smartico/public-api';
+   *
+   * const board = await window._smartico.api.getLeaderBoard(LeaderBoardPeriodType.WEEKLY);
+   *
+   * if (!board) {
+   *   console.log('[smartico] no weekly board configured for this label — hide the leaderboard surface');
+   *   return;
+   * }
+   *
+   * console.log('[smartico] render leaderboard tab —', board.name, '—', board.users.length, 'ranked entries (top 20 max)');
+   *
+   * // Render prize table.
+   * for (const reward of board.rewards) {
+   *   console.log('[smartico] prize row — place', reward.place, '→', reward.points, 'points');
+   * }
+   *
+   * // "Me" panel — sticky row showing the current user's rank.
+   * if (board.me) {
+   *   if (board.me.position === -1) {
+   *     console.log('[smartico] user is unranked — show "You are unranked, earn points to enter the leaderboard"');
+   *   } else if (board.me.position > 20) {
+   *     console.log('[smartico] user is ranked', board.me.position, 'but outside the visible top-20 — show sticky "me" row with', board.me.points, 'points');
+   *   } else {
+   *     console.log('[smartico] user is in the top 20 at position', board.me.position, '— highlight their row in the main list');
+   *   }
+   * }
+   *
+   * // Switch to previous period view — but bust the cache first to avoid the shared-key collision.
+   * await window._smartico.api.clearCaches();
+   * const prev = await window._smartico.api.getLeaderBoard(LeaderBoardPeriodType.WEEKLY, true);
+   * console.log('[smartico] previous-week standings — render with greyed-out "ended" treatment:', prev?.users.length, 'finalists');
+   *
+   * // Visitor-mode equivalent — me is always undefined.
+   * // const visitorBoard = await window._smartico.vapi('EN').getLeaderBoard(LeaderBoardPeriodType.DAILY);
    * ```
    */
   async getLeaderBoard(periodType, getPreviousPeriod) {
@@ -5968,23 +8263,49 @@ class WSAPILeaderBoard extends WSAPIGamePick {
 /** @group Inbox */
 class WSAPIInbox extends WSAPILeaderBoard {
   /**
-   * 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.
+   * Records that an engagement (inbox message, popup) was displayed to
+   * the user. Use this to drive engagement analytics — every visible
+   * inbox message should fire one impression event per render
+   * occurrence, and every popup display should fire one.
    *
-   * **Example**:
-   * ```
-   * _smartico.api.reportImpressionEvent({
-   *      engagement_uid: 'abc123-def456',
-   *      activityType: 31 // Inbox
-   * });
-   * ```
+   * **Fire-and-forget**: the call is asynchronous and one-way — there
+   * is no response promise to await and no error reporting. The SDK
+   * swallows transport failures silently. Returns `void`.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **When to call**
+   * - Inbox: when a message becomes visible (the user opens / scrolls
+   *   it into view). The default Smartico UI fires this when the
+   *   message detail expands, alongside
+   *   {@link markInboxMessageAsRead}.
+   * - Popup: when the popup content is shown to the user.
+   *
+   * **Activity types**
+   * Pass {@link ActivityTypeLimited.Inbox} (`31`) for inbox messages,
+   * {@link ActivityTypeLimited.Popup} (`30`) for popups. Other values
+   * are not used by the engagement-impression channel.
+   *
+   * **Idempotency**: the server records every impression event —
+   * repeated calls add to the impression count. Don't fire it on
+   * every re-render; fire it once per logical "display" event
+   * (modal open, list-row scroll-into-view, popup show).
+   *
+   * **Side effects**: server-side increments the engagement's
+   * `impression_count` and updates `last_impression_date`. The
+   * counter is observable via operator analytics; the SDK consumer
+   * receives no signal back.
+   *
+   * **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)
+   * @example
+   * ```ts
+   * // When the user opens an inbox message in the detail view.
+   * window._smartico.api.reportImpressionEvent({
+   *   engagement_uid: message.message_guid,
+   *   activityType: 31,  // ActivityTypeLimited.Inbox
+   * });
+   * console.log('[smartico] inbox impression reported for', message.message_guid, '— no response to await, fire-and-forget');
+   * ```
    */
   reportImpressionEvent({
     engagement_uid,
@@ -5993,25 +8314,54 @@ class WSAPIInbox extends WSAPILeaderBoard {
     this.api.reportEngagementImpression(this.userExtId, engagement_uid, activityType);
   }
   /**
-   * 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.
+   * Records that the user interacted with an engagement — typically
+   * tapping a CTA button, following a deep-link, or clicking a popup
+   * action. Use this to drive engagement analytics on what users
+   * actually act on (vs what they merely see —
+   * {@link reportImpressionEvent}).
    *
-   * **Example**:
-   * ```
-   * _smartico.api.reportClickEvent({
-   *      engagement_uid: 'abc123-def456',
-   *      activityType: 31 // Inbox
-   *      action: 'dp:gf_missions'
-   * });
-   * ```
+   * **Fire-and-forget**: the call is asynchronous and one-way — there
+   * is no response promise to await and no error reporting. The SDK
+   * swallows transport failures silently. Returns `void`.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **When to call**
+   * - Inbox: when the user taps a CTA button on a message or follows
+   *   a deep-link inside the message body. Pass the deep-link or URL
+   *   as `action`.
+   * - Popup: when the user clicks a popup action button.
+   *
+   * **Activity types**
+   * Pass {@link ActivityTypeLimited.Inbox} (`31`) for inbox,
+   * {@link ActivityTypeLimited.Popup} (`30`) for popups.
+   *
+   * **`action` payload**
+   * Pass the deep-link or URL that the user triggered (e.g.
+   * `'dp:gf_missions'`, `'https://example.com/promo'`). The SDK
+   * forwards the string to the server for analytics — it does not
+   * execute the deep-link. To execute deep-links safely, call
+   * `_smartico.dp(action)` separately.
+   *
+   * **Idempotency**: the server records every click event —
+   * repeated calls add to the count. Fire once per logical user
+   * action.
+   *
+   * **Side effects**: server-side updates the engagement's
+   * `last_action` field; observable via operator analytics. The SDK
+   * consumer receives no signal back.
    *
-   * @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
+   * **Visitor mode**: not supported.
+   *
+   * @example
+   * ```ts
+   * // When the user taps a CTA button in an inbox message.
+   * window._smartico.api.reportClickEvent({
+   *   engagement_uid: message.message_guid,
+   *   activityType: 31,  // ActivityTypeLimited.Inbox
+   *   action: 'dp:gf_missions',
+   * });
+   * window._smartico.dp('dp:gf_missions');   // separately execute the deep-link
+   * ```
    */
   reportClickEvent({
     engagement_uid,
@@ -6020,19 +8370,118 @@ class WSAPIInbox extends WSAPILeaderBoard {
   }) {
     this.api.reportEngagementAction(this.userExtId, engagement_uid, activityType, action);
   }
-  /** 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.
+  /**
+   * Returns the user's inbox messages — newest first — with optional
+   * filtering by category, favorite status, and read state. Each
+   * `TInboxMessage` is a lightweight envelope (`message_guid`,
+   * `sent_date`, `read`, `favorite`, `category_id`, `expire_on_dt`);
+   * fetch the rich body (title, preview, icon, html_body, buttons)
+   * separately via {@link getInboxMessageBody}.
    *
-   * **Visitor mode: not supported**
+   * Use this to power an inbox list screen. Subscribe via `onUpdate`
+   * to react to newly-arrived messages pushed by the server (from
+   * campaigns, automation rules, manual operator sends).
+   *
+   * @remarks
+   * **Subscription model (`onUpdate`)**
+   * The callback receives the FULL refreshed message list (never a
+   * diff/patch). Each subsequent call to `getInboxMessages({ 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** — the callback fires ONLY when:
+   *
+   * 1. A new message is pushed by the server (campaign / automation /
+   *    operator send). The refreshed list includes the new message
+   *    at the top.
+   *
+   * Does NOT fire for: `markInboxMessageAsRead`,
+   * `markAllInboxMessagesAsRead`,
+   * `markUnmarkInboxMessageAsFavorite`, `deleteInboxMessage`,
+   * `deleteAllInboxMessages`. After a mutation, re-call
+   * `getInboxMessages` manually if your UI needs the refreshed list
+   * — or maintain optimistic state locally.
+   *
+   * **Pagination**
+   * `from` (defaults to `0`) and `to` (defaults to `20`) define a
+   * half-open range of message indices. The server caps the page at
+   * **20 messages per request** — passing `to - from > 20` silently
+   * truncates to 20. For "load more" pagination, advance `from` by
+   * the prior page size on each subsequent call.
+   *
+   * **Filters**
+   * All filters are ANDed server-side. Omitting a filter means "no
+   * constraint" on that dimension:
+   * - `categoryId` ({@link InboxCategories}): `General` (0),
+   *   `Platform` (1), `Personal` (2). Omit to get all categories.
+   * - `onlyFavorite: true` returns only starred messages.
+   *   Omit / `false` returns all (starred and not).
+   * - `read_status` ({@link InboxReadStatus}): `UnreadOnly` (1) or
+   *   `ReadOnly` (2). Omit to get both.
+   *
+   * **Server-side filtering** (always applied)
+   * Expired messages (`expire_on_dt` in the past) and
+   * soft-deleted messages are excluded server-side. Consumers do not
+   * need to filter for these.
+   *
+   * **No client cache**: every call sends a fresh server round-trip.
+   * To avoid redundant fetches in your UI, hold the result in
+   * application state and re-fetch on `onUpdate` fires or explicit
+   * user-driven refresh.
+   *
+   * **Idempotency / Side effects**: safe. Read-only.
+   *
+   * **UI guidance**: see [UI Guide — `getInboxMessages`](../../docs/ui/inbox/UIGuide_getInboxMessages.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param params              Optional filters + subscription.
+   * @param params.from         First message index (0-based). Defaults
+   *                            to `0`.
+   * @param params.to           Last message index (exclusive).
+   *                            Defaults to `20`. Server caps the page
+   *                            at 20.
+   * @param params.onlyFavorite When `true`, returns only favorite
+   *                            (starred) messages.
+   * @param params.categoryId   When set, returns only messages in this
+   *                            category ({@link InboxCategories}).
+   * @param params.read_status  When set, scopes to read or unread
+   *                            only ({@link InboxReadStatus}).
+   * @param params.onUpdate     Callback invoked with the full
+   *                            refreshed list when a new message
+   *                            arrives.
+   *
+   * @returns Promise resolving to up to 20 `TInboxMessage` envelopes.
+   *          Empty array when the user has no messages matching the
+   *          filter.
+   *
+   * @example
+   * ```ts
+   * const messages = await window._smartico.api.getInboxMessages({
+   *   onUpdate: (refreshed) => {
+   *     console.log('[smartico] new inbox message arrived — re-render the list from this array, new message is at index 0:', refreshed);
+   *   },
+   * });
    *
-   * @param params
+   * // For each message, fetch its body for the list view (title, preview, icon).
+   * for (const msg of messages) {
+   *   const body = await window._smartico.api.getInboxMessageBody(msg.message_guid);
+   *   console.log('[smartico] render message', msg.message_guid,
+   *     '— title:', body.title,
+   *     '— preview:', body.preview_body,
+   *     '— read:', msg.read,
+   *     '— favorite:', msg.favorite);
+   * }
+   *
+   * // "Load more" pagination — advance from by the prior page size.
+   * const page2 = await window._smartico.api.getInboxMessages({ from: 20, to: 40 });
+   * console.log('[smartico] page 2:', page2.length, 'messages');
+   *
+   * // Filter examples.
+   * const onlyStarred = await window._smartico.api.getInboxMessages({ onlyFavorite: true });
+   * const onlyUnread = await window._smartico.api.getInboxMessages({ read_status: 1 });  // InboxReadStatus.UnreadOnly
+   * ```
    */
   async getInboxMessages({
     from,
@@ -6048,10 +8497,53 @@ class WSAPIInbox extends WSAPILeaderBoard {
     return await this.api.getInboxMessagesT(this.userExtId, from, to, onlyFavorite, categoryId, read_status);
   }
   /**
-   * Returns inbox unread count.
+   * Returns the user's current unread inbox message count — a single
+   * integer suitable for driving a header badge. Optionally subscribe
+   * to live updates via `onUpdate`.
    *
-   * **Visitor mode: not supported**
-   * @param params
+   * For most UIs, prefer `core_inbox_unread_count` from
+   * {@link getUserProfile} instead: it carries the same value, is
+   * push-updated in real time via the user-properties channel, and
+   * doesn't require a separate cache. This method is useful when you
+   * want a dedicated subscription tied to the inbox surface rather
+   * than the broader user-properties channel.
+   *
+   * @remarks
+   * **Subscription model**
+   * `onUpdate` fires whenever the cached value changes — either on a
+   * push from the user-properties channel (new message arrival,
+   * mark-as-read, delete) or after an inbox-list fetch that returns
+   * a fresh count.
+   *
+   * **Cache TTL**: 30 seconds. The cached value is patched in place
+   * by push events (no full re-fetch on every push), so the
+   * `onUpdate` callback reflects server state with sub-second latency
+   * regardless of the TTL.
+   *
+   * **Idempotency / Side effects**: safe. Read-only.
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param params           Optional subscription bag.
+   * @param params.onUpdate  Callback invoked with the new unread
+   *                         count whenever it changes (push-driven).
+   * @returns                Promise resolving to the current unread
+   *                         count (integer, includes `0`).
+   *
+   * @example
+   * ```ts
+   * // Static read for an initial badge render.
+   * const count = await window._smartico.api.getInboxUnreadCount();
+   * console.log('[smartico] inbox badge initial count:', count);
+   *
+   * // Live subscription for badge updates.
+   * await window._smartico.api.getInboxUnreadCount({
+   *   onUpdate: (newCount) => {
+   *     console.log('[smartico] inbox count changed — update the badge to:', newCount,
+   *       '— hide badge entirely when 0, show raw integer otherwise (no "99+" cap in the default UI)');
+   *   },
+   * });
+   * ```
    */
   async getInboxUnreadCount({
     onUpdate
@@ -6062,17 +8554,113 @@ class WSAPIInbox extends WSAPILeaderBoard {
     return OCache.use(onUpdateContextKey.InboxUnreadCount, ECacheContext.WSAPI, () => this.api.getInboxUnreadCountT(this.userExtId), CACHE_DATA_SEC);
   }
   /**
-   * Returns the message body of the specified message guid.
+   * Returns the rich body of a single inbox message — title, preview
+   * text, icon, click action, optional rich HTML body, and optional
+   * buttons. Call this after fetching the envelope list via
+   * {@link getInboxMessages} to render either a list-item preview or
+   * a full detail view.
+   *
+   * The message body is served from a CDN — not over the WebSocket —
+   * so latency depends on CDN proximity rather than WS round-trip
+   * time. There is NO client-side cache; every call is a fresh
+   * HTTP fetch. Browser HTTP caching applies (Cache-Control headers
+   * from the CDN), but the SDK does not memoize the result.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Rich vs simple messages**
+   * The shape of the returned body branches on the `action` field:
+   * - When `action === 'dp:inbox'`, the message has a rich HTML body
+   *   (`html_body`) and may have up to 2 action `buttons`. Use these
+   *   for a full-detail rendering.
+   * - For any other `action` (deep-link like `'dp:deposit'` or a URL),
+   *   the message is a simple notification — `html_body` and
+   *   `buttons` will be `undefined` regardless of what's in the
+   *   underlying CDN payload. Render `title` + `preview_body` + a
+   *   single CTA driving the `action`.
+   *
+   * **The `action` field**
+   * For both shapes, `action` carries either a deep-link
+   * (`'dp:gf_missions'`) or a plain URL. Pass it to `_smartico.dp()`
+   * for safe execution — that helper handles URL vs deep-link
+   * routing.
+   *
+   * **Idempotency / Side effects**: safe. Read-only HTTP fetch.
+   *
+   * **UI guidance**: see [UI Guide — `getInboxMessageBody`](../../docs/ui/inbox/UIGuide_getInboxMessageBody.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param messageGuid  The `message_guid` from a `TInboxMessage`
+   *                     returned by {@link getInboxMessages}.
+   * @returns            Promise resolving to `TInboxMessageBody`.
+   *
+   * @example
+   * ```ts
+   * const body = await window._smartico.api.getInboxMessageBody(messageGuid);
+   *
+   * console.log('[smartico] render message — title:', body.title,
+   *   '— preview:', body.preview_body,
+   *   '— icon:', body.icon);
+   *
+   * if (body.action === 'dp:inbox' && body.html_body) {
+   *   console.log('[smartico] rich message — render the html_body in a sandboxed iframe; render up to 2 action buttons:',
+   *     body.buttons?.length ?? 0);
+   * } else {
+   *   console.log('[smartico] simple message — show preview_body + single CTA wired to:', body.action,
+   *     '— execute via _smartico.dp(body.action)');
+   * }
+   * ```
    */
   async getInboxMessageBody(messageGuid) {
     return await this.api.getInboxMessageBodyT(messageGuid);
   }
   /**
-   * Requests to mark inbox message with specified guid as read
+   * Marks a single inbox message as read. Server-side this flips the
+   * message's `is_read` flag and decrements the user's unread count
+   * (the change propagates back via the user-properties channel —
+   * subscribers to {@link getInboxUnreadCount}'s `onUpdate` and
+   * {@link getUserProfile}'s `core_inbox_unread_count` see it within
+   * ~1 second).
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Error codes** (in `err_code`)
+   * - `0` — success; the message is now marked read. Idempotent — a
+   *   second call on the same `messageGuid` also returns `0`.
+   * - other non-zero — server error. Surface `err_message` if any.
+   *
+   * **Refresh after success**
+   * The SDK does NOT auto-refresh {@link getInboxMessages} (no
+   * `onUpdate` callback fires after this mutation). The unread-count
+   * channel ({@link getInboxUnreadCount}, `core_inbox_unread_count`)
+   * DOES auto-update — subscribers to it see the new count
+   * automatically. If your inbox list UI shows the `read` field, you
+   * have two options: re-call `getInboxMessages` after the mutation,
+   * or update the local copy optimistically.
+   *
+   * **Idempotency**: safe. Repeated calls return `err_code === 0`.
+   *
+   * **Side effects** (on success)
+   * - Server-side `is_read` flag set to true.
+   * - Server-side `core_inbox_unread_count` decremented (if the
+   *   message was previously unread).
+   *
+   * **UI guidance**: see [UI Guide — `markInboxMessageAsRead`](../../docs/ui/inbox/UIGuide_markInboxMessageAsRead.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param messageGuid  The `message_guid` from a `TInboxMessage`.
+   * @returns `{ err_code, err_message }`; success when
+   *          `err_code === 0`.
+   *
+   * @example
+   * ```ts
+   * const r = await window._smartico.api.markInboxMessageAsRead(message.message_guid);
+   * if (r.err_code === 0) {
+   *   console.log('[smartico] marked as read — optimistically flip the local read indicator; the inbox badge auto-decrements via the user-properties channel');
+   * } else {
+   *   console.error('[smartico] mark-as-read failed — keep the local state as-is and show a non-blocking error if appropriate:', r.err_message);
+   * }
+   * ```
    */
   async markInboxMessageAsRead(messageGuid) {
     const r = await this.api.markInboxMessageRead(this.userExtId, messageGuid);
@@ -6082,9 +8670,57 @@ class WSAPIInbox extends WSAPILeaderBoard {
     };
   }
   /**
-   * Requests to mark all inbox messages as read
+   * Marks ALL of the user's inbox messages as read in one server
+   * round-trip — typically wired to a "Mark all as read" CTA in the
+   * inbox header.
    *
-   * **Visitor mode: not supported**
+   * The operation is global to the user — NOT filtered by the
+   * current view (active category tab, favorite filter, etc.). Every
+   * unread message in the user's inbox flips to read.
+   *
+   * @remarks
+   * **Error codes** (in `err_code`)
+   * - `0` — success; all currently-unread messages flipped to read.
+   * - other non-zero — server error. Surface `err_message` if any.
+   *
+   * **Race condition note**: a new message arriving server-side
+   * between the call and its processing remains unread (the
+   * server's mark-all operation is a snapshot in time). Subsequent
+   * `getInboxMessages` calls show the new message as unread.
+   *
+   * **Refresh after success**
+   * Same as {@link markInboxMessageAsRead} — `getInboxMessages`
+   * `onUpdate` does NOT fire automatically, but the unread-count
+   * channel does (the badge will drop to 0, or to the count of any
+   * new messages that arrived during processing).
+   *
+   * **Idempotency**: safe. A second call on an already-all-read
+   * inbox returns `err_code === 0` with no-op effect.
+   *
+   * **Side effects** (on success)
+   * - Every unread message flipped to read.
+   * - `core_inbox_unread_count` drops to 0 (or near 0 if races).
+   *
+   * **UI guidance**: included in the
+   * [UI Guide — `markInboxMessageAsRead`](../../docs/ui/inbox/UIGuide_markInboxMessageAsRead.md)
+   * (Bulk variant section).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @returns `{ err_code, err_message }`; success when
+   *          `err_code === 0`.
+   *
+   * @example
+   * ```ts
+   * console.log('[smartico] mark-all-read starting — set in-flight flag on the "Mark all read" button, show loading dots');
+   * const r = await window._smartico.api.markAllInboxMessagesAsRead();
+   * console.log('[smartico] mark-all-read response — clear in-flight flag');
+   * if (r.err_code === 0) {
+   *   console.log('[smartico] all messages marked read — optimistically flip every local read indicator; badge auto-drops via user-properties channel');
+   * } else {
+   *   console.error('[smartico] mark-all failed — surface a non-blocking error:', r.err_message);
+   * }
+   * ```
    */
   async markAllInboxMessagesAsRead() {
     const r = await this.api.markAllInboxMessageRead(this.userExtId);
@@ -6094,9 +8730,57 @@ class WSAPIInbox extends WSAPILeaderBoard {
     };
   }
   /**
-   * Requests to mark inbox message with specified guid as favorite. Pass mark true to add message to favorite and false to remove.
+   * Toggles a message's favorite (starred) state — pass `mark: true`
+   * to favorite, `mark: false` to unfavorite. Use to power a star
+   * icon click handler on the inbox list.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Error codes** (in `err_code`)
+   * - `0` — success; the message's favorite state flipped to the
+   *   requested value.
+   * - other non-zero — server error. Surface `err_message` if any.
+   *
+   * **Refresh after success**
+   * The SDK does NOT auto-refresh {@link getInboxMessages}. To
+   * reflect the new state in the UI, update the local copy of the
+   * affected `TInboxMessage` (set `favorite` to the new value) or
+   * re-call `getInboxMessages`.
+   *
+   * **Idempotency**: safe. `mark: true` on an already-favorite
+   * message returns `err_code === 0` (no-op). Same for `mark: false`
+   * on a non-favorite.
+   *
+   * **Side effects** (on success)
+   * - Server-side `is_starred` flag set to the requested value.
+   * - No effect on read state, unread count, or other fields.
+   *
+   * **UI guidance**: see [UI Guide — `markUnmarkInboxMessageAsFavorite`](../../docs/ui/inbox/UIGuide_markUnmarkInboxMessageAsFavorite.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param messageGuid  The `message_guid` from a `TInboxMessage`.
+   * @param mark         `true` to favorite, `false` to unfavorite.
+   * @returns            `{ err_code, err_message }`; success when
+   *                     `err_code === 0`.
+   *
+   * @example
+   * ```ts
+   * // Toggle handler — flip the local state optimistically, then
+   * // call the server, and revert if the call fails.
+   * const target = !message.favorite;
+   * console.log('[smartico] optimistically flip the star to', target, '— it will revert if the server rejects');
+   *
+   * const r = await window._smartico.api.markUnmarkInboxMessageAsFavorite(
+   *   message.message_guid,
+   *   target,
+   * );
+   *
+   * if (r.err_code === 0) {
+   *   console.log('[smartico] favorite toggled — keep the local state and show a brief "Added to favorites" / "Removed from favorites" toast');
+   * } else {
+   *   console.error('[smartico] favorite toggle failed — revert the local state and show an error toast:', r.err_message);
+   * }
+   * ```
    */
   async markUnmarkInboxMessageAsFavorite(messageGuid, mark) {
     const r = await this.api.markUnmarkInboxMessageAsFavorite(this.userExtId, messageGuid, mark);
@@ -6106,9 +8790,52 @@ class WSAPIInbox extends WSAPILeaderBoard {
     };
   }
   /**
-   * Requests to delete inbox message
+   * Soft-deletes a single inbox message. After deletion, the message
+   * is excluded from future {@link getInboxMessages} responses
+   * server-side, but its row is retained for analytics — there is no
+   * "undelete" path via the SDK.
    *
-   * **Visitor mode: not supported**
+   * @remarks
+   * **Error codes** (in `err_code`)
+   * - `0` — success; the message is now deleted from the user's
+   *   view.
+   * - other non-zero — server error. Surface `err_message` if any.
+   *
+   * **Refresh after success**
+   * The SDK does NOT auto-refresh {@link getInboxMessages}. Drop the
+   * deleted message from your local list, or re-call
+   * `getInboxMessages` to reload. If the deleted message was unread,
+   * the unread count drops automatically via the user-properties
+   * channel.
+   *
+   * **Idempotency**: safe. A second call on an already-deleted
+   * `messageGuid` returns `err_code === 0` (server treats it as a
+   * no-op — already-deleted messages are filtered out).
+   *
+   * **Side effects** (on success)
+   * - Server-side `is_deleted` flag set to true.
+   * - If the message was unread, `core_inbox_unread_count`
+   *   decrements via the user-properties channel.
+   *
+   * **UI guidance**: see [UI Guide — `deleteInboxMessage`](../../docs/ui/inbox/UIGuide_deleteInboxMessage.md).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @param messageGuid  The `message_guid` from a `TInboxMessage`.
+   * @returns `{ err_code, err_message }`; success when
+   *          `err_code === 0`.
+   *
+   * @example
+   * ```ts
+   * // Swipe-to-delete on mobile; trash-icon click on desktop.
+   * console.log('[smartico] delete starting — animate the row out of the list (slide left/right by 100%)');
+   * const r = await window._smartico.api.deleteInboxMessage(message.message_guid);
+   * if (r.err_code === 0) {
+   *   console.log('[smartico] deleted — drop the message from the local list, fire a brief "Message deleted" toast (no undo affordance — there is no undelete via the SDK)');
+   * } else {
+   *   console.error('[smartico] delete failed — animate the row back into place and show a non-blocking error:', r.err_message);
+   * }
+   * ```
    */
   async deleteInboxMessage(messageGuid) {
     const r = await this.api.deleteInboxMessage(this.userExtId, messageGuid);
@@ -6118,9 +8845,61 @@ class WSAPIInbox extends WSAPILeaderBoard {
     };
   }
   /**
-   * Requests to delete all inbox messages
+   * Soft-deletes ALL of the user's inbox messages in one server
+   * round-trip — typically wired to a "Delete all" CTA in the inbox
+   * header (usually behind a confirm dialog given the destructive
+   * nature).
    *
-   * **Visitor mode: not supported**
+   * The operation is global to the user — NOT filtered by the
+   * current view (active category tab, favorite filter, etc.). Every
+   * non-deleted message in the user's inbox flips to deleted.
+   *
+   * @remarks
+   * **Error codes** (in `err_code`)
+   * - `0` — success; the entire inbox is now empty from the user's
+   *   view.
+   * - other non-zero — server error. Surface `err_message` if any.
+   *
+   * **Race condition note**: a new message arriving server-side
+   * between the call and its processing is NOT deleted (the
+   * server's delete-all operation is a snapshot in time). Subsequent
+   * `getInboxMessages` calls show the new message.
+   *
+   * **Refresh after success**
+   * Same as {@link deleteInboxMessage} — `getInboxMessages` `onUpdate`
+   * does not fire automatically. Replace the local list with `[]`
+   * (or re-call `getInboxMessages`). The unread count drops to 0
+   * (or near-0 if races) via the user-properties channel.
+   *
+   * **Idempotency**: safe. A second call on an already-empty inbox
+   * returns `err_code === 0` with no-op effect.
+   *
+   * **Side effects** (on success)
+   * - Every message flipped to deleted server-side.
+   * - `core_inbox_unread_count` drops to 0.
+   * - There is no SDK undelete path — recovery requires operator
+   *   intervention.
+   *
+   * **UI guidance**: included in the
+   * [UI Guide — `deleteInboxMessage`](../../docs/ui/inbox/UIGuide_deleteInboxMessage.md)
+   * (Bulk variant section).
+   *
+   * **Visitor mode**: not supported.
+   *
+   * @returns `{ err_code, err_message }`; success when
+   *          `err_code === 0`.
+   *
+   * @example
+   * ```ts
+   * // After a confirm dialog "Are you sure you want to delete all messages?"
+   * console.log('[smartico] delete-all confirmed — show loading state on the "Delete all" button');
+   * const r = await window._smartico.api.deleteAllInboxMessages();
+   * if (r.err_code === 0) {
+   *   console.log('[smartico] inbox cleared — replace the local list with [], fire a "All messages deleted" toast, badge auto-drops to 0');
+   * } else {
+   *   console.error('[smartico] delete-all failed — show a non-blocking error toast:', r.err_message);
+   * }
+   * ```
    */
   async deleteAllInboxMessages() {
     const r = await this.api.deleteAllInboxMessages(this.userExtId);
@@ -7468,6 +10247,10 @@ class SmarticoAPI {
     const message = this.buildMessage(user_ext_id, ClassId.RAF_OPTIN_REQUEST, props);
     return await this.send(message, ClassId.RAF_OPTIN_RESPONSE);
   }
+  async getRaffleWonPrizes(user_ext_id, props) {
+    const message = this.buildMessage(user_ext_id, ClassId.RAF_GET_WON_PRIZES_REQUEST, props);
+    return await this.send(message, ClassId.RAF_GET_WON_PRIZES_RESPONSE);
+  }
   async getActivityLog(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset) {
     const message = this.buildMessage(user_ext_id, ClassId.GET_POINT_HISTORY_REQUEST, {
       startTimeSeconds: Math.floor(startTimeSeconds),