@smartico/public-api 0.0.385 → 0.0.386

package/dist/index.modern.mjs

@@ -2009,20 +2009,50 @@ const tournamentInfoItemTransform = t => {
   return response;
 };
 
+/**
+ * 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.
+ */
 var TournamentRegistrationError;
 (function (TournamentRegistrationError) {
+  /** Success — registration persisted; buy-in (if any) deducted. */
   TournamentRegistrationError[TournamentRegistrationError["NO_ERROR"] = 0] = "NO_ERROR";
+  /** Clan-based tournament and the user does not belong to a clan yet. */
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_USER_CANNOT_JOIN_WITHOUT_CLAN"] = 1010] = "TOURNAMENT_USER_CANNOT_JOIN_WITHOUT_CLAN";
+  /** Instance id is invalid or the tournament was deleted. */
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_INSTANCE_NOT_FOUND"] = 30001] = "TOURNAMENT_INSTANCE_NOT_FOUND";
+  /** Insufficient points balance for a points-priced buy-in. */
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_REGISTRATION_NOT_ENOUGH_POINTS"] = 30002] = "TOURNAMENT_REGISTRATION_NOT_ENOUGH_POINTS";
+  /** Tournament is no longer in a registerable state (finished, cancelled, finalizing, or not yet open). */
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_INSTANCE_NOT_IN_STATE"] = 30003] = "TOURNAMENT_INSTANCE_NOT_IN_STATE";
+  /** User is already registered; treat as an idempotent success. */
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_ALREADY_REGISTERED"] = 30004] = "TOURNAMENT_ALREADY_REGISTERED";
+  /** User does not satisfy the tournament's segment / entry conditions. */
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_USER_DONT_MATCH_CONDITIONS"] = 30005] = "TOURNAMENT_USER_DONT_MATCH_CONDITIONS";
+  /** User is not registered; anomalous on a register call (usually a server-side race). */
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_USER_NOT_REGISTERED"] = 30006] = "TOURNAMENT_USER_NOT_REGISTERED";
+  /** Registration status transition is not allowed (e.g. re-registering a finished tournament). */
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_CANT_CHANGE_REGISTRATION_STATUS"] = 30007] = "TOURNAMENT_CANT_CHANGE_REGISTRATION_STATUS";
+  /** Tournament filled up — maximum registrations reached. */
   TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_MAX_REGISTRATIONS_REACHED"] = 30008] = "TOURNAMENT_MAX_REGISTRATIONS_REACHED";
-  TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_REGISTRATION_NOT_ENOUGH_GEMS"] = 30010] = "TOURNAMENT_REGISTRATION_NOT_ENOUGH_GEMS";
-  TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_REGISTRATION_NOT_ENOUGH_DIAMONDS"] = 30011] = "TOURNAMENT_REGISTRATION_NOT_ENOUGH_DIAMONDS";
+  /**
+   * 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.
+   */
+  TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_INVALID_USER_CURRENCY"] = 30009] = "TOURNAMENT_INVALID_USER_CURRENCY";
+  /** Insufficient gems balance for a gems-priced buy-in. */
+  TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_REGISTRATION_NOT_ENOUGH_GEMS"] = 300010] = "TOURNAMENT_REGISTRATION_NOT_ENOUGH_GEMS";
+  /** Insufficient diamonds balance for a diamonds-priced buy-in. */
+  TournamentRegistrationError[TournamentRegistrationError["TOURNAMENT_REGISTRATION_NOT_ENOUGH_DIAMONDS"] = 300011] = "TOURNAMENT_REGISTRATION_NOT_ENOUGH_DIAMONDS";
 })(TournamentRegistrationError || (TournamentRegistrationError = {}));
 
 var TournamentType;
@@ -2744,12 +2774,25 @@ 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
@@ -2777,10 +2820,10 @@ 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);
    *   }
@@ -2815,14 +2858,12 @@ 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
@@ -3313,8 +3354,14 @@ 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.
    *
@@ -3356,6 +3403,12 @@ class WSAPIMissions extends WSAPIGeneral {
    * ```
    */
   async getBadges() {
+    // 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);
   }
   /**
@@ -5434,12 +5487,10 @@ 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
@@ -8180,15 +8231,8 @@ 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
@@ -8258,8 +8302,7 @@ 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');
    *
@@ -8268,7 +8311,10 @@ class WSAPILeaderBoard extends WSAPIGamePick {
    * ```
    */
   async getLeaderBoard(periodType, getPreviousPeriod) {
-    return OCache.use(onUpdateContextKey.LeaderBoards, ECacheContext.WSAPI, () => this.api.leaderboardsGetT(this.userExtId, periodType, getPreviousPeriod), CACHE_DATA_SEC);
+    // 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(cacheKey, ECacheContext.WSAPI, () => this.api.leaderboardsGetT(this.userExtId, periodType, getPreviousPeriod), CACHE_DATA_SEC);
   }
 }
 
@@ -8993,6 +9039,7 @@ class WSAPI extends WSAPIInbox {
         if ((data == null || (_data$props3 = data.props) == null ? void 0 : _data$props3.ach_points_balance) !== undefined || (data == null || (_data$props4 = data.props) == null ? void 0 : _data$props4.ach_gems_balance) !== undefined || (data == null || (_data$props5 = data.props) == null ? void 0 : _data$props5.ach_diamonds_balance) !== undefined) {
           this.notifyActivityLogUpdate();
         }
+        OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.CurrentLevel);
       });
       on(ClassId.RAF_OPTIN_RESPONSE, () => this.updateRaffles());
     }
@@ -10888,31 +10935,37 @@ const AvatarCustomizeErrorMessage = {
   [AvatarCustomizeErrorCode.AVATAR_LABEL_LIMIT]: 'The custom avatars are not available, please try again later'
 };
 
-/*
- *  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.
  */
 var JoinClanErrorCode;
 (function (JoinClanErrorCode) {
-  /** No error, join completed */
+  /** Success — join completed; entry fee (if any) deducted. */
   JoinClanErrorCode[JoinClanErrorCode["JOIN_CLAN_OK"] = 0] = "JOIN_CLAN_OK";
-  /** Invalid parameters */
+  /** Request was malformed (missing or invalid parameters). */
   JoinClanErrorCode[JoinClanErrorCode["JOIN_CLAN_INVALID_PARAMETERS"] = 1000] = "JOIN_CLAN_INVALID_PARAMETERS";
-  /** clan_id doesn't exist for this label */
+  /** Clan doesn't exist for this label. Archived clans are also reported as `1001`. */
   JoinClanErrorCode[JoinClanErrorCode["JOIN_CLAN_NOT_FOUND"] = 1001] = "JOIN_CLAN_NOT_FOUND";
-  /** members_count >= capacity_limit */
+  /** Clan is full — member capacity reached. */
   JoinClanErrorCode[JoinClanErrorCode["JOIN_CLAN_FULL"] = 1002] = "JOIN_CLAN_FULL";
-  /** Not enough Points / Gems / Diamonds for entry fee */
+  /** Insufficient balance for the entry fee (points / gems / diamonds). */
   JoinClanErrorCode[JoinClanErrorCode["JOIN_CLAN_INSUFFICIENT_FUNDS"] = 1003] = "JOIN_CLAN_INSUFFICIENT_FUNDS";
-  /** User doesn't satisfy entry_conditions / entry_segment_id */
+  /** User doesn't meet the clan's entry segment or conditions. */
   JoinClanErrorCode[JoinClanErrorCode["JOIN_CLAN_SEGMENT_MISMATCH"] = 1004] = "JOIN_CLAN_SEGMENT_MISMATCH";
-  /** 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`.
+   */
   JoinClanErrorCode[JoinClanErrorCode["JOIN_CLAN_USER_IS_NOT_IN_CLAN"] = 1005] = "JOIN_CLAN_USER_IS_NOT_IN_CLAN";
-  /** User is within the CLAN_COOLDOWN_DAYS window */
+  /** User is within the clan-switch cooldown window (switch only). */
   JoinClanErrorCode[JoinClanErrorCode["JOIN_CLAN_COOLDOWN_ACTIVE"] = 1006] = "JOIN_CLAN_COOLDOWN_ACTIVE";
-  /** clan_status_id != 1 (clan is archived) */
-  JoinClanErrorCode[JoinClanErrorCode["JOIN_CLAN_ARCHIVED"] = 1007] = "JOIN_CLAN_ARCHIVED";
-  /** Clan joined after tournament start */
+  /**
+   * Clan joined after tournament start. Note: a `registerInTournament`
+   * response code that shares this enum — never returned by `joinClan`.
+   */
   JoinClanErrorCode[JoinClanErrorCode["JOIN_CLAN_JOINED_AFTER_TOURNAMENT_START"] = 1011] = "JOIN_CLAN_JOINED_AFTER_TOURNAMENT_START";
 })(JoinClanErrorCode || (JoinClanErrorCode = {}));