@smartico/public-api 0.0.384 → 0.0.386

package/docs/api/classes/WSAPILeaderBoard.md

@@ -80,15 +80,8 @@ 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.
+**Cache TTL**
+The SDK caches each response for 30 seconds. 
 
 **Period boundaries**
 The server finalizes each period on a server-configurable
@@ -145,8 +138,7 @@ if (board.me) {
   }
 }
 
-// Switch to previous period view — but bust the cache first to avoid the shared-key collision.
-await window._smartico.api.clearCaches();
+// Switch to previous period view — cached separately from the current period.
 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');
 

package/docs/api/classes/WSAPIMissions.md

@@ -205,8 +205,17 @@ metadata and group badges by category.
 **Idempotency / Side effects**: fetch-only; safe to call repeatedly.
 The cache layer deduplicates concurrent calls within the TTL window.
 
+**Visitor mode**: not supported. Badges are an authenticated-only
+feature; calling this on the visitor-mode handle (`_smartico.vapi`)
+throws synchronously rather than silently returning an empty list.
+
 **UI guidance**: see [UI Guide — `getBadges`](../../ui/missions/UIGuide_getBadges.md).
 
+#### Throws
+
+`Error("getBadges is not available in visitor mode")` when
+        called from a visitor-mode session.
+
 #### Example
 
 ```ts

package/docs/api/classes/WSAPIUser.md

@@ -401,12 +401,25 @@ source values directly from [getUserProfile](#getuserprofile)'s
 `ach_points_ever` and [getLevels](#getlevels) would also work, but
 `progress` saves the math.
 
-**Cache TTL**: the SDK caches the response for 30 seconds. There is
-no push event that refreshes this cache; a server-side level change
-(visible immediately on [getUserProfile](#getuserprofile)'s `ach_level_current_id`
-via the user-properties update channel) becomes visible on this
-method only after the cache TTL expires, or after
-`_smartico.api.clearCaches()` is called.
+**Cache TTL & freshness**
+The response is cached for 30 seconds, but the SDK automatically
+drops that cache whenever a user-properties update arrives — the
+same live channel that backs [getUserProfile](#getuserprofile). The practical
+effect depends on the label's leveling logic:
+- **Points-based or operator-manual leveling**: a points or level
+  change flows through the user-properties channel, so the cache is
+  busted at that moment and the next `getCurrentLevel()` call
+  returns up-to-date data without waiting out the TTL.
+- **Counter-based leveling** (level driven by sliding-window
+  counters such as deposit or wagering totals over a recent window —
+  see [getUserLevelExtraCounters](#getuserlevelextracounters)): ordinary progress changes
+  are recomputed by a periodic server job and do NOT emit a
+  user-properties update, so they become visible on this method only
+  after the 30 s TTL expires (or after `_smartico.api.clearCaches()`).
+
+Avoid calling `clearCaches()` on the points/manual path — it's
+unnecessary there (the cache is already refreshed on the property
+update) and forces a slower extra round-trip.
 
 **Leveling logic**
 The semantics of how a user advances depends on the label's
@@ -432,10 +445,10 @@ const level = await window._smartico.api.getCurrentLevel();
 console.log('[smartico] render level badge — name:', level.name,
   'progress:', Math.round(level.progress), '%');
 
-// Detect level-up via getUserProfile's push channel.
+// Detect level-up via getUserProfile's push channel. No clearCaches()
+// needed — the SDK already drops the level cache on this update.
 window._smartico.on('props_change', async (changed) => {
   if ('ach_level_current_id' in changed) {
-    await window._smartico.api.clearCaches();   // bust the 30 s cache
     const fresh = await window._smartico.api.getCurrentLevel();
     console.log('[smartico] user levelled up — animate badge to new level:', fresh.name);
   }
@@ -481,14 +494,12 @@ stored under the translation keys `levelsCounter1Name` and
 `levelsCounter2Name`.
 
 **Refresh cadence**
-Sliding-window counters are recomputed by a server-side job that
-runs roughly every 60 seconds against the operator's BigQuery
-dataset; level transitions driven by counter changes have a
-latency of up to several minutes after the underlying activity
-(e.g. a deposit). The SDK caches the response for 30 seconds; no
-push event refreshes this cache. After a level change visible on
-[getUserProfile](#getuserprofile)'s `ach_level_current_id`, call
-`_smartico.api.clearCaches()` to force a fresh fetch.
+Sliding-window counters are recomputed by a periodic server-side
+job. Its rebuild cadence is operator-configured per brand —
+commonly daily, though it can be set more frequent — so level
+transitions driven by counter changes surface with a latency tied
+to that rebuild schedule after the underlying activity (e.g. a
+deposit), not in real time.
 
 **Idempotency**: safe. Read-only. Repeated calls within the cache
 window return a deep-cloned cached value without a network

package/docs/api/enumerations/TournamentRegistrationError.md

@@ -1,73 +1,118 @@
 # Enumeration: TournamentRegistrationError
 
+Error codes returned in `err_code` by the `registerInTournament` method.
+
+These are terse value definitions for lookup. The full per-code narrative —
+when each fires and how the consumer's UI should react — lives in the
+`registerInTournament` method TSDoc, which owns the error table.
+
+Note the numbering break: the gems / diamonds codes are 6-digit
+(`300010` / `300011`) while the rest of the tournament block is 5-digit;
+they were appended after the original `30001`–`30009` range was occupied.
+Branch on the exact numeric value, not on digit count.
+
 ## Enumeration Members
 
 ### NO\_ERROR
 
 > **NO\_ERROR**: `0`
 
+Success — registration persisted; buy-in (if any) deducted.
+
 ***
 
 ### TOURNAMENT\_USER\_CANNOT\_JOIN\_WITHOUT\_CLAN
 
 > **TOURNAMENT\_USER\_CANNOT\_JOIN\_WITHOUT\_CLAN**: `1010`
 
+Clan-based tournament and the user does not belong to a clan yet.
+
 ***
 
 ### TOURNAMENT\_INSTANCE\_NOT\_FOUND
 
 > **TOURNAMENT\_INSTANCE\_NOT\_FOUND**: `30001`
 
+Instance id is invalid or the tournament was deleted.
+
 ***
 
 ### TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_POINTS
 
 > **TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_POINTS**: `30002`
 
+Insufficient points balance for a points-priced buy-in.
+
 ***
 
 ### TOURNAMENT\_INSTANCE\_NOT\_IN\_STATE
 
 > **TOURNAMENT\_INSTANCE\_NOT\_IN\_STATE**: `30003`
 
+Tournament is no longer in a registerable state (finished, cancelled, finalizing, or not yet open).
+
 ***
 
 ### TOURNAMENT\_ALREADY\_REGISTERED
 
 > **TOURNAMENT\_ALREADY\_REGISTERED**: `30004`
 
+User is already registered; treat as an idempotent success.
+
 ***
 
 ### TOURNAMENT\_USER\_DONT\_MATCH\_CONDITIONS
 
 > **TOURNAMENT\_USER\_DONT\_MATCH\_CONDITIONS**: `30005`
 
+User does not satisfy the tournament's segment / entry conditions.
+
 ***
 
 ### TOURNAMENT\_USER\_NOT\_REGISTERED
 
 > **TOURNAMENT\_USER\_NOT\_REGISTERED**: `30006`
 
+User is not registered; anomalous on a register call (usually a server-side race).
+
 ***
 
 ### TOURNAMENT\_CANT\_CHANGE\_REGISTRATION\_STATUS
 
 > **TOURNAMENT\_CANT\_CHANGE\_REGISTRATION\_STATUS**: `30007`
 
+Registration status transition is not allowed (e.g. re-registering a finished tournament).
+
 ***
 
 ### TOURNAMENT\_MAX\_REGISTRATIONS\_REACHED
 
 > **TOURNAMENT\_MAX\_REGISTRATIONS\_REACHED**: `30008`
 
+Tournament filled up — maximum registrations reached.
+
+***
+
+### TOURNAMENT\_INVALID\_USER\_CURRENCY
+
+> **TOURNAMENT\_INVALID\_USER\_CURRENCY**: `30009`
+
+The user's wallet currency could not be resolved. Emitted server-side
+during tournament score processing, NOT during registration — it is
+never returned by `registerInTournament`. Included for completeness.
+
 ***
 
 ### TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_GEMS
 
-> **TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_GEMS**: `30010`
+> **TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_GEMS**: `300010`
+
+Insufficient gems balance for a gems-priced buy-in.
 
 ***
 
 ### TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_DIAMONDS
 
-> **TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_DIAMONDS**: `30011`
+> **TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_DIAMONDS**: `300011`
+
+Insufficient diamonds balance for a diamonds-priced buy-in.

package/docs/ui/clans/UIGuide_joinClan.md

@@ -76,8 +76,7 @@ table of codes; UI handling per code:
 | `1003` (insufficient funds) | Show insufficient-balance UI naming the currency (`['points','gems','diamonds'][entry_fee_currency_type_id]`) and the deficit (`entry_fee_amount`). Optional: deep-link to a currency-earning surface. |
 | `1004` (segment mismatch) | Show a gating message — operator-supplied copy if the clan exposes one; otherwise a generic "Not eligible for this clan". Don't retry. |
 | `1005` | `joinClan` does NOT return `1005`. If you see it in this method's response, treat as a generic error. |
-| `1006` (cooldown active) | Show "Cooldown until {cooldown_until local-formatted}". Disable the Join CTA across ALL clans until cooldown expires. |
-| `1007` (archived) | Defined in the public enum but the server emits `1001` instead. Handle as a synonym for `1001` defensively. |
+| `1006` (cooldown active) | Show "Cooldown until {cooldown_until local-formatted}". Disable the Join CTA across ALL clans until cooldown expires. Only fires when the user is already in a *different* clan (a switch); a first-time join never returns it. |
 | `1011` | `joinClan` does NOT return `1011`. If you see it in this method's response, treat as a generic error. |
 | Other | Generic error toast with `errMsg` if any. |
 

package/docs/ui/leaderboard/UIGuide_getLeaderBoard.md

@@ -4,8 +4,8 @@
 - Returns the top-20 ranked entries for one period, the current user's
   own rank, and the configured prize table.
 - One call per (period type, current-or-previous) — the SDK caches
-  under a single key, so switching periods or current/previous within
-  30 s returns stale cached data unless `clearCaches()` is invoked.
+  each combination independently for 30 s, so switching periods or
+  current/previous fetches the correct board (no cross-tab collision).
 - No subscription, no push refresh. Poll manually if the consumer
   needs live updates during an in-progress period.
 
@@ -92,15 +92,13 @@ content.
 
 When the user switches between current and previous period:
 
-1. Call `clearCaches()` to bust the shared OCache key
-   (otherwise the second call returns stale data within 30 s).
-2. Call `getLeaderBoard(periodType, getPreviousPeriod)` with the new
-   `getPreviousPeriod` value.
-3. Replace the rendered data.
+1. Call `getLeaderBoard(periodType, getPreviousPeriod)` with the new
+   `getPreviousPeriod` value — current and previous are cached under
+   distinct keys, so no manual cache-busting is needed.
+2. Replace the rendered data.
 
 ```ts
 const onTogglePrevious = async (showPrevious: boolean) => {
-  await window._smartico.api.clearCaches();
   const board = await window._smartico.api.getLeaderBoard(
     activePeriodType,
     showPrevious,
@@ -109,8 +107,11 @@ const onTogglePrevious = async (showPrevious: boolean) => {
 };
 ```
 
-Same pattern applies when switching between period types
-(`DAILY` → `WEEKLY` → `MONTHLY`).
+The same holds when switching between period types
+(`DAILY` → `WEEKLY` → `MONTHLY`): each is cached separately. To force
+a fresh fetch within the TTL (e.g. a manual refresh button), call
+`clearCaches()` first — it clears the whole SDK cache, not just this
+board.
 
 ## Status-specific visual treatments
 
@@ -155,10 +156,10 @@ Same pattern applies when switching between period types
 
 ## Performance
 
-- The 30 s cache deduplicates rapid refetches, but the single-key
-  design means switching periods within the window returns stale
-  data. `clearCaches()` is the only way to force a fresh fetch
-  before the TTL expires.
+- The 30 s cache deduplicates rapid refetches and is keyed per
+  `(periodType, getPreviousPeriod)`, so switching tabs returns the
+  correct board. `clearCaches()` forces a fresh fetch before the TTL
+  expires (it clears the entire SDK cache).
 - For live polling during an in-progress period, ~30 s cadence is
   appropriate (matching the cache TTL — additional polls within
   the window are free).

package/package.json

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

package/src/Clans/JoinClanErrorCode.ts

@@ -1,26 +1,32 @@
-/*
- *  Possible error codes returned in JOIN_CLAN_RESPONSE.errCode (cid: 575).
- *  Clan-protocol-specific numeric codes defined in the handler spec.
+/**
+ * Error codes returned in `errCode` by the `joinClan` method (also carried
+ * on `TClanJoinResult`). These are terse value definitions for lookup; the
+ * full per-code narrative and UI handling lives in the `joinClan` method
+ * TSDoc, which owns the error table.
  */
 export enum JoinClanErrorCode {
-	/** No error, join completed */
+	/** Success — join completed; entry fee (if any) deducted. */
 	JOIN_CLAN_OK = 0,
-	/** Invalid parameters */
+	/** Request was malformed (missing or invalid parameters). */
 	JOIN_CLAN_INVALID_PARAMETERS = 1000,
-	/** clan_id doesn't exist for this label */
+	/** Clan doesn't exist for this label. Archived clans are also reported as `1001`. */
 	JOIN_CLAN_NOT_FOUND = 1001,
-	/** members_count >= capacity_limit */
+	/** Clan is full — member capacity reached. */
 	JOIN_CLAN_FULL = 1002,
-	/** Not enough Points / Gems / Diamonds for entry fee */
+	/** Insufficient balance for the entry fee (points / gems / diamonds). */
 	JOIN_CLAN_INSUFFICIENT_FUNDS = 1003,
-	/** User doesn't satisfy entry_conditions / entry_segment_id */
+	/** User doesn't meet the clan's entry segment or conditions. */
 	JOIN_CLAN_SEGMENT_MISMATCH = 1004,
-	/** User is not in a clan */
+	/**
+	 * User is not in a clan. Note: a `registerInTournament` response code
+	 * that shares this enum — never returned by `joinClan`.
+	 */
 	JOIN_CLAN_USER_IS_NOT_IN_CLAN = 1005,
-	/** User is within the CLAN_COOLDOWN_DAYS window */
+	/** User is within the clan-switch cooldown window (switch only). */
 	JOIN_CLAN_COOLDOWN_ACTIVE = 1006,
-	/** clan_status_id != 1 (clan is archived) */
-	JOIN_CLAN_ARCHIVED = 1007,
-	/** Clan joined after tournament start */
+	/**
+	 * Clan joined after tournament start. Note: a `registerInTournament`
+	 * response code that shares this enum — never returned by `joinClan`.
+	 */
 	JOIN_CLAN_JOINED_AFTER_TOURNAMENT_START = 1011,
 }

package/src/Inbox/InboxMessage.ts

@@ -53,6 +53,9 @@ export interface InboxMessage {
 }
 
 export const InboxMessageBodyTransform = (item: InboxMessageBody): TInboxMessageBody => {
+	if (!item) {
+		return null;
+	}
 	const x: TInboxMessageBody = {
 		action: item.action,
 		icon: item.image,

package/src/Tournaments/Tournament.ts

@@ -76,7 +76,7 @@ export interface Tournament {
 
 export const TournamentItemsTransform = (items: Tournament[]): TTournament[] => {
 	return items
-		.filter((r) => r.tournamentId >= 1)
+		.filter((r) => r != null && r.tournamentId >= 1)
 		.map((r) => {
 			const x: TTournament = {
 				instance_id: r.tournamentInstanceId,

package/src/Tournaments/TournamentRegistrationError.ts

@@ -1,16 +1,44 @@
+/**
+ * Error codes returned in `err_code` by the `registerInTournament` method.
+ *
+ * These are terse value definitions for lookup. The full per-code narrative —
+ * when each fires and how the consumer's UI should react — lives in the
+ * `registerInTournament` method TSDoc, which owns the error table.
+ *
+ * Note the numbering break: the gems / diamonds codes are 6-digit
+ * (`300010` / `300011`) while the rest of the tournament block is 5-digit;
+ * they were appended after the original `30001`–`30009` range was occupied.
+ * Branch on the exact numeric value, not on digit count.
+ */
 export enum TournamentRegistrationError {
+	/** Success — registration persisted; buy-in (if any) deducted. */
 	NO_ERROR = 0,
+	/** Clan-based tournament and the user does not belong to a clan yet. */
 	TOURNAMENT_USER_CANNOT_JOIN_WITHOUT_CLAN = 1010,
+	/** Instance id is invalid or the tournament was deleted. */
 	TOURNAMENT_INSTANCE_NOT_FOUND = 30001,
+	/** Insufficient points balance for a points-priced buy-in. */
 	TOURNAMENT_REGISTRATION_NOT_ENOUGH_POINTS = 30002,
+	/** Tournament is no longer in a registerable state (finished, cancelled, finalizing, or not yet open). */
 	TOURNAMENT_INSTANCE_NOT_IN_STATE = 30003,
+	/** User is already registered; treat as an idempotent success. */
 	TOURNAMENT_ALREADY_REGISTERED = 30004,
+	/** User does not satisfy the tournament's segment / entry conditions. */
 	TOURNAMENT_USER_DONT_MATCH_CONDITIONS = 30005,
+	/** User is not registered; anomalous on a register call (usually a server-side race). */
 	TOURNAMENT_USER_NOT_REGISTERED = 30006,
+	/** Registration status transition is not allowed (e.g. re-registering a finished tournament). */
 	TOURNAMENT_CANT_CHANGE_REGISTRATION_STATUS = 30007,
+	/** Tournament filled up — maximum registrations reached. */
 	TOURNAMENT_MAX_REGISTRATIONS_REACHED = 30008,
-    TOURNAMENT_REGISTRATION_NOT_ENOUGH_GEMS = 30010,
-    TOURNAMENT_REGISTRATION_NOT_ENOUGH_DIAMONDS = 30011,
-
-
+	/**
+	 * The user's wallet currency could not be resolved. Emitted server-side
+	 * during tournament score processing, NOT during registration — it is
+	 * never returned by `registerInTournament`. Included for completeness.
+	 */
+	TOURNAMENT_INVALID_USER_CURRENCY = 30009,
+	/** Insufficient gems balance for a gems-priced buy-in. */
+	TOURNAMENT_REGISTRATION_NOT_ENOUGH_GEMS = 300010,
+	/** Insufficient diamonds balance for a diamonds-priced buy-in. */
+	TOURNAMENT_REGISTRATION_NOT_ENOUGH_DIAMONDS = 300011,
 }

package/src/WSAPI/WSAPI.ts

@@ -5,6 +5,7 @@ import { SmarticoAPI } from '../SmarticoAPI';
 import { JackpotWinPush, JackpotsOptinResponse, JackpotsOptoutRequest } from '../Jackpots';
 import { onUpdateContextKey } from './WSAPIBase';
 import { WSAPIInbox } from './WSAPIInbox';
+import { TUserProfile } from './WSAPITypes';
 
 /**
  * Public surface of the Smartico WebSocket API. The consumer reaches every
@@ -64,13 +65,14 @@ export class WSAPI extends WSAPIInbox {
 					this.updateInboxUnreadCount(res.unread_count);
 				}
 			});
-			on(ClassId.CLIENT_PUBLIC_PROPERTIES_CHANGED_EVENT, (data: { props: { core_inbox_unread_count?: number; ach_points_balance?: number; ach_gems_balance?: number; ach_diamonds_balance?: number } }) => {
+			on(ClassId.CLIENT_PUBLIC_PROPERTIES_CHANGED_EVENT, (data: { props: TUserProfile }) => {
 				if (data?.props?.core_inbox_unread_count !== undefined && data?.props?.core_inbox_unread_count !== null) {
 					this.updateInboxUnreadCount(data.props.core_inbox_unread_count);
 				}
 				if (data?.props?.ach_points_balance !== undefined || data?.props?.ach_gems_balance !== undefined || data?.props?.ach_diamonds_balance !== undefined) {
 					this.notifyActivityLogUpdate();
 				}
+				OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.CurrentLevel);
 			});
 			on(ClassId.RAF_OPTIN_RESPONSE, () => this.updateRaffles());
 		}

package/src/WSAPI/WSAPIClans.ts

@@ -303,12 +303,10 @@ export class WSAPIClans extends WSAPITournaments {
 	 *   tournament requires the user to be in a clan first.
 	 * - `1006` (`JOIN_CLAN_COOLDOWN_ACTIVE`) — user is inside the
 	 *   switch-cooldown window from a previous clan join (default
-	 *   7 days, configurable per label). Surface the
+	 *   7 days, configurable per label). Only reachable when the user is
+	 *   already in a *different* clan (this call is then a clan switch);
+	 *   a first-time join never returns `1006`. Surface the
 	 *   `TClans.cooldown_until` expiry in the disabled CTA.
-	 * - `1007` (`JOIN_CLAN_ARCHIVED`) — defined on the public enum but
-	 *   the server does NOT emit this code in practice (archived clans
-	 *   are reported as `1001`). Handle it as a synonym for `1001`
-	 *   defensively, but do not rely on it.
 	 * - `1011` (`JOIN_CLAN_JOINED_AFTER_TOURNAMENT_START`) — this
 	 *   method does NOT return `1011` directly. The code fires on
 	 *   {@link registerInTournament} responses when the user joined

package/src/WSAPI/WSAPIJackpots.ts

@@ -121,6 +121,9 @@ export class WSAPIJackpots extends WSAPIClans {
 			ECacheContext.WSAPI,
 			async () => {
 				const _jackpots = await this.api.jackpotGet(this.userExtId, filter);
+				if (!_jackpots?.items) {
+					return [];
+				}
 				const _pots = _jackpots.items.map((jp) => jp.pot);
 
 				_jackpots.items.forEach((jp) => {

package/src/WSAPI/WSAPILeaderBoard.ts

@@ -56,15 +56,8 @@ export class WSAPILeaderBoard extends WSAPIGamePick {
 	 * 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.
+	 * **Cache TTL**
+	 * The SDK caches each response for 30 seconds. 
 	 *
 	 * **Period boundaries**
 	 * The server finalizes each period on a server-configurable
@@ -134,8 +127,7 @@ export class WSAPILeaderBoard extends WSAPIGamePick {
 	 *   }
 	 * }
 	 *
-	 * // Switch to previous period view — but bust the cache first to avoid the shared-key collision.
-	 * await window._smartico.api.clearCaches();
+	 * // Switch to previous period view — cached separately from the current period.
 	 * 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');
 	 *
@@ -144,8 +136,11 @@ export class WSAPILeaderBoard extends WSAPIGamePick {
 	 * ```
 	 */
 	public async getLeaderBoard(periodType: LeaderBoardPeriodType, getPreviousPeriod?: boolean): Promise<LeaderBoardDetailsT> {
+		// Cache per (periodType, current/previous) so switching tabs or
+		// current↔previous within the TTL doesn't return a colliding board.
+		const cacheKey = `${onUpdateContextKey.LeaderBoards}:${periodType}:${getPreviousPeriod ? 1 : 0}`;
 		return OCache.use(
-			onUpdateContextKey.LeaderBoards,
+			cacheKey,
 			ECacheContext.WSAPI,
 			() => this.api.leaderboardsGetT(this.userExtId, periodType, getPreviousPeriod),
 			CACHE_DATA_SEC,

package/src/WSAPI/WSAPIMiniGames.ts

@@ -586,6 +586,9 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 			CACHE_DATA_SEC,
 		);
 		const index = templates.findIndex((t) => t.id === data.saw_template_id);
+		if (index === -1) {
+			return;
+		}
 		templates[index].spin_count = data.spin_count;
 		this.updateEntity(onUpdateContextKey.Saw, templates);
 	}

package/src/WSAPI/WSAPIMissions.ts

@@ -198,8 +198,14 @@ export class WSAPIMissions extends WSAPIGeneral {
 	 * **Idempotency / Side effects**: fetch-only; safe to call repeatedly.
 	 * The cache layer deduplicates concurrent calls within the TTL window.
 	 *
+	 * **Visitor mode**: not supported. Badges are an authenticated-only
+	 * feature; calling this on the visitor-mode handle (`_smartico.vapi`)
+	 * throws synchronously rather than silently returning an empty list.
+	 *
 	 * **UI guidance**: see [UI Guide — `getBadges`](../../docs/ui/missions/UIGuide_getBadges.md).
 	 *
+	 * @throws `Error("getBadges is not available in visitor mode")` when
+	 *         called from a visitor-mode session.
 	 * @returns Promise resolving to `TMissionOrBadge[]`. Every item has
 	 *          `type === 'badge'`. Cached for 30 s under the `Badges` key.
 	 *
@@ -241,6 +247,12 @@ export class WSAPIMissions extends WSAPIGeneral {
 	 * ```
 	 */
 	public async getBadges(): Promise<TMissionOrBadge[]> {
+		// Badges are an authenticated-only feature. The visitor-mode WSAPI
+		// instance (`_smartico.vapi`) is constructed without a tracker, so the
+		// server would silently return nothing; throw a clear error instead.
+		if (!this.api.tracker) {
+			throw new Error('getBadges is not available in visitor mode');
+		}
 		return OCache.use(onUpdateContextKey.Badges, ECacheContext.WSAPI, () => this.api.badgetsGetItemsT(this.userExtId), CACHE_DATA_SEC);
 	}
 

package/src/WSAPI/WSAPIUser.ts

@@ -371,12 +371,25 @@ export class WSAPIUser extends WSAPIBase {
 	 * `ach_points_ever` and {@link getLevels} would also work, but
 	 * `progress` saves the math.
 	 *
-	 * **Cache TTL**: the SDK caches the response for 30 seconds. There is
-	 * no push event that refreshes this cache; a server-side level change
-	 * (visible immediately on {@link getUserProfile}'s `ach_level_current_id`
-	 * via the user-properties update channel) becomes visible on this
-	 * method only after the cache TTL expires, or after
-	 * `_smartico.api.clearCaches()` is called.
+	 * **Cache TTL & freshness**
+	 * The response is cached for 30 seconds, but the SDK automatically
+	 * drops that cache whenever a user-properties update arrives — the
+	 * same live channel that backs {@link getUserProfile}. The practical
+	 * effect depends on the label's leveling logic:
+	 * - **Points-based or operator-manual leveling**: a points or level
+	 *   change flows through the user-properties channel, so the cache is
+	 *   busted at that moment and the next `getCurrentLevel()` call
+	 *   returns up-to-date data without waiting out the TTL.
+	 * - **Counter-based leveling** (level driven by sliding-window
+	 *   counters such as deposit or wagering totals over a recent window —
+	 *   see {@link getUserLevelExtraCounters}): ordinary progress changes
+	 *   are recomputed by a periodic server job and do NOT emit a
+	 *   user-properties update, so they become visible on this method only
+	 *   after the 30 s TTL expires (or after `_smartico.api.clearCaches()`).
+	 *
+	 * Avoid calling `clearCaches()` on the points/manual path — it's
+	 * unnecessary there (the cache is already refreshed on the property
+	 * update) and forces a slower extra round-trip.
 	 *
 	 * **Leveling logic**
 	 * The semantics of how a user advances depends on the label's
@@ -404,10 +417,10 @@ export class WSAPIUser extends WSAPIBase {
 	 * console.log('[smartico] render level badge — name:', level.name,
 	 *   'progress:', Math.round(level.progress), '%');
 	 *
-	 * // Detect level-up via getUserProfile's push channel.
+	 * // Detect level-up via getUserProfile's push channel. No clearCaches()
+	 * // needed — the SDK already drops the level cache on this update.
 	 * window._smartico.on('props_change', async (changed) => {
 	 *   if ('ach_level_current_id' in changed) {
-	 *     await window._smartico.api.clearCaches();   // bust the 30 s cache
 	 *     const fresh = await window._smartico.api.getCurrentLevel();
 	 *     console.log('[smartico] user levelled up — animate badge to new level:', fresh.name);
 	 *   }
@@ -443,14 +456,12 @@ export class WSAPIUser extends WSAPIBase {
 	 * `levelsCounter2Name`.
 	 *
 	 * **Refresh cadence**
-	 * Sliding-window counters are recomputed by a server-side job that
-	 * runs roughly every 60 seconds against the operator's BigQuery
-	 * dataset; level transitions driven by counter changes have a
-	 * latency of up to several minutes after the underlying activity
-	 * (e.g. a deposit). The SDK caches the response for 30 seconds; no
-	 * push event refreshes this cache. After a level change visible on
-	 * {@link getUserProfile}'s `ach_level_current_id`, call
-	 * `_smartico.api.clearCaches()` to force a fresh fetch.
+	 * Sliding-window counters are recomputed by a periodic server-side
+	 * job. Its rebuild cadence is operator-configured per brand —
+	 * commonly daily, though it can be set more frequent — so level
+	 * transitions driven by counter changes surface with a latency tied
+	 * to that rebuild schedule after the underlying activity (e.g. a
+	 * deposit), not in real time.
 	 *
 	 * **Idempotency**: safe. Read-only. Repeated calls within the cache
 	 * window return a deep-cloned cached value without a network