@smartico/public-api 0.0.385 → 0.0.387

package/README.md

@@ -74,7 +74,7 @@ The SDK surface is split across one class per feature area, joined by an interna
 | **Jackpots** | [`WSAPIJackpots`](docs/api/classes/WSAPIJackpots.md) | `jackpotGet`, `jackpotOptIn`, `jackpotOptOut`, `getJackpotWinners`, `getJackpotEligibleGames` | [`jackpotGet`](docs/ui/jackpots/UIGuide_jackpotGet.md) · [`jackpotOptIn`](docs/ui/jackpots/UIGuide_jackpotOptIn.md) · [`jackpotOptOut`](docs/ui/jackpots/UIGuide_jackpotOptOut.md) · [`getJackpotWinners`](docs/ui/jackpots/UIGuide_getJackpotWinners.md) · [`getJackpotEligibleGames`](docs/ui/jackpots/UIGuide_getJackpotEligibleGames.md) |
 | **Raffles / Draws** | [`WSAPIRaffles`](docs/api/classes/WSAPIRaffles.md) | `getRaffles`, `getRaffleDrawRun`, `getRaffleDrawRunsHistory`, `claimRafflePrize`, `requestRaffleOptin`, `getRaffleWonPrizes` | [`getRaffles`](docs/ui/raffles/UIGuide_getRaffles.md) · [`getRaffleDrawRun`](docs/ui/raffles/UIGuide_getRaffleDrawRun.md) · [`getRaffleDrawRunsHistory`](docs/ui/raffles/UIGuide_getRaffleDrawRunsHistory.md) · [`claimRafflePrize`](docs/ui/raffles/UIGuide_claimRafflePrize.md) · [`requestRaffleOptin`](docs/ui/raffles/UIGuide_requestRaffleOptin.md) · [`getRaffleWonPrizes`](docs/ui/raffles/UIGuide_getRaffleWonPrizes.md) |
 | **MiniGames / SAW** | [`WSAPIMiniGames`](docs/api/classes/WSAPIMiniGames.md) | `getMiniGames`, `getMiniGamesHistory`, `playMiniGame`, `miniGameWinAcknowledgeRequest`, `playMiniGameBatch` | [`getMiniGames`](docs/ui/minigames/UIGuide_getMiniGames.md) · [`getMiniGamesHistory`](docs/ui/minigames/UIGuide_getMiniGamesHistory.md) · [`playMiniGame`](docs/ui/minigames/UIGuide_playMiniGame.md) · [`playMiniGameBatch`](docs/ui/minigames/UIGuide_playMiniGameBatch.md) |
-| **Avatars** | [`WSAPIAvatars`](docs/api/classes/WSAPIAvatars.md) | `getAvatarsList`, `getAvatarsCustomized`, `getAvatarPrompts`, `setAvatar` | [`getAvatarsList`](docs/ui/avatars/UIGuide_getAvatarsList.md) · [`getAvatarsCustomized`](docs/ui/avatars/UIGuide_getAvatarsCustomized.md) · [`getAvatarPrompts`](docs/ui/avatars/UIGuide_getAvatarPrompts.md) · [`setAvatar`](docs/ui/avatars/UIGuide_setAvatar.md) |
+| **Avatars** | [`WSAPIAvatars`](docs/api/classes/WSAPIAvatars.md) | `getAvatarsList`, `getAvatarsCustomized`, `getAvatarPrompts`, `setAvatar`, `avatarsCustomize` | [`getAvatarsList`](docs/ui/avatars/UIGuide_getAvatarsList.md) · [`getAvatarsCustomized`](docs/ui/avatars/UIGuide_getAvatarsCustomized.md) · [`getAvatarPrompts`](docs/ui/avatars/UIGuide_getAvatarPrompts.md) · [`setAvatar`](docs/ui/avatars/UIGuide_setAvatar.md) · [`avatarsCustomize`](docs/ui/avatars/UIGuide_avatarsCustomize.md) |
 | **Game Pick (sports / quiz)** | [`WSAPIGamePick`](docs/api/classes/WSAPIGamePick.md) | `gamePickGet*`, `gamePickSubmit*` (9 methods) | [`gamePickGetActiveRounds`](docs/ui/gamepick/UIGuide_gamePickGetActiveRounds.md) · [`gamePickGetActiveRound`](docs/ui/gamepick/UIGuide_gamePickGetActiveRound.md) · [`gamePickGetHistory`](docs/ui/gamepick/UIGuide_gamePickGetHistory.md) · [`gamePickGetBoard`](docs/ui/gamepick/UIGuide_gamePickGetBoard.md) · [`gamePickSubmitSelection`](docs/ui/gamepick/UIGuide_gamePickSubmitSelection.md) · [`gamePickSubmitSelectionQuiz`](docs/ui/gamepick/UIGuide_gamePickSubmitSelectionQuiz.md) · [`gamePickGetUserInfo`](docs/ui/gamepick/UIGuide_gamePickGetUserInfo.md) · [`gamePickGetGameInfo`](docs/ui/gamepick/UIGuide_gamePickGetGameInfo.md) · [`gamePickGetRoundInfoForUser`](docs/ui/gamepick/UIGuide_gamePickGetRoundInfoForUser.md) |
 | **Leaderboard** | [`WSAPILeaderBoard`](docs/api/classes/WSAPILeaderBoard.md) | `getLeaderBoard` | [`getLeaderBoard`](docs/ui/leaderboard/UIGuide_getLeaderBoard.md) |
 | **Inbox / Messages / Engagement** | [`WSAPIInbox`](docs/api/classes/WSAPIInbox.md) | `getInboxMessages`, `getInboxUnreadCount`, `getInboxMessageBody`, `markInboxMessageAsRead`, `markAllInboxMessagesAsRead`, `markUnmarkInboxMessageAsFavorite`, `deleteInboxMessage`, `deleteAllInboxMessages`, `reportImpressionEvent`, `reportClickEvent` | [`getInboxMessages`](docs/ui/inbox/UIGuide_getInboxMessages.md) · [`getInboxMessageBody`](docs/ui/inbox/UIGuide_getInboxMessageBody.md) · [`markInboxMessageAsRead`](docs/ui/inbox/UIGuide_markInboxMessageAsRead.md) · [`markUnmarkInboxMessageAsFavorite`](docs/ui/inbox/UIGuide_markUnmarkInboxMessageAsFavorite.md) · [`deleteInboxMessage`](docs/ui/inbox/UIGuide_deleteInboxMessage.md) |

package/dist/Avatars/AvatarCustomizeErrorCode.d.ts

@@ -1,5 +1,11 @@
+/**
+ * Limit error codes returned in `errCode` by the `avatarsCustomize` method.
+ * See the `avatarsCustomize` TSDoc for the full table (including the generic
+ * `-1` failure, which has no named member here).
+ */
 export declare enum AvatarCustomizeErrorCode {
+    /** The user has reached the operator-configured per-user monthly cap on custom-avatar generations. */
     AVATAR_USER_LIMIT = 12001,
+    /** The brand's operator-configured shared monthly pool of custom-avatar generations is exhausted. */
     AVATAR_LABEL_LIMIT = 12002
 }
-export declare const AvatarCustomizeErrorMessage: Record<AvatarCustomizeErrorCode, string>;

package/dist/Avatars/AvatarCustomizeResponse.d.ts

@@ -0,0 +1,16 @@
+import { AvatarCustomizeErrorCode } from './AvatarCustomizeErrorCode';
+/**
+ * Result of `_smartico.api.avatarsCustomize()`. On success only `cdn_url` is
+ * set; on failure only `errCode` / `errMessage`.
+ */
+export interface AvatarCustomizeResponse {
+    /** CDN URL of the generated avatar variant. Present on success. */
+    cdn_url?: string;
+    /** Error code. Present on failure. Typed values are members of
+     * {@link AvatarCustomizeErrorCode}; `-1` is a generic failure. See the
+     * `avatarsCustomize` TSDoc for the full table. */
+    errCode?: AvatarCustomizeErrorCode | number;
+    /** Optional error message. Present on failure; the generic (`-1`) message
+     * is fixed text, so branch on `errCode`, not this string. */
+    errMessage?: string;
+}

package/dist/Avatars/index.d.ts

@@ -1,4 +1,5 @@
 export * from './AvatarCustomizeErrorCode';
+export * from './AvatarCustomizeResponse';
 export * from './AvatarDefinition';
 export * from './AvatarCustomized';
 export * from './AvatarPrompt';

package/dist/Clans/JoinClanErrorCode.d.ts

@@ -1,22 +1,32 @@
+/**
+ * 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 declare 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/dist/Missions/UserAchievementTask.d.ts

@@ -5,6 +5,10 @@ export interface UserAchievementTask {
     task_id?: number;
     task_public_meta?: AchievementTaskPublicMeta;
     points_reward?: number;
+    /** Gems awarded when this task is completed. */
+    gems_reward?: number;
+    /** Diamonds awarded when this task is completed. */
+    diamonds_reward?: number;
     task_type_id: AchievementTaskType;
     isCompleted?: boolean;
     userExecutedCount?: number;

package/dist/SmarticoAPI.d.ts

@@ -28,6 +28,7 @@ import { GetAvatarsListResponse } from './Avatars/GetAvatarsListResponse';
 import { GetAvatarsCustomizedResponse } from './Avatars/GetAvatarsCustomizedResponse';
 import { GetAvatarPromptsResponse } from './Avatars/GetAvatarPromptsResponse';
 import { SetAvatarResponse } from './Avatars';
+import { AvatarCustomizeResponse } from './Avatars/AvatarCustomizeResponse';
 import { GetJackpotWinnersResponse, JackpotWinnerHistory } from './Jackpots/GetJackpotWinnersResponse';
 import { GetJackpotEligibleGamesResponse, TGetJackpotEligibleGamesResponse } from './Jackpots/GetJackpotEligibleGamesResponse';
 import { GamePickGameInfo, GamePickRound, GamePickRoundBoard, GamePickUserInfo, GamesApiResponse } from './GamePick';
@@ -61,6 +62,7 @@ declare class SmarticoAPI {
     private gamesApiUrl;
     private baseRgApiParams;
     avatarDomain: string;
+    private avatarOriginDomain;
     private envId;
     private logger;
     private logCIDs;
@@ -76,6 +78,7 @@ declare class SmarticoAPI {
     static getPublicUrl(label_api_key: string): string;
     static getPublicWsUrl(label_api_key: string): string;
     static getAvatarUrl(label_api_key: string): string;
+    static getAvatarOriginUrl(label_api_key: string): string;
     private send;
     private buildMessage;
     coreReportCustomEvent(user_ext_id: string, eventType: string, payload?: any): Promise<any>;
@@ -175,6 +178,7 @@ declare class SmarticoAPI {
     deleteAllInboxMessages(user_ext_id: string): Promise<MarkInboxMessageDeletedResponse>;
     private buildGamesApiParams;
     private sendGamesApi;
+    private sendAvatarApi;
     gpGetActiveRounds(saw_template_id: number): Promise<GamesApiResponse<GamePickRound[]>>;
     gpGetActiveRound(saw_template_id: number, round_id?: number): Promise<GamesApiResponse<GamePickRound>>;
     gpGetGamesHistory(saw_template_id: number): Promise<GamesApiResponse<GamePickRound[]>>;
@@ -188,6 +192,13 @@ declare class SmarticoAPI {
     avatarsGetCustomized(user_ext_id: string): Promise<GetAvatarsCustomizedResponse>;
     avatarsGetPrompts(user_ext_id: string): Promise<GetAvatarPromptsResponse>;
     avatarSetAvatar(user_ext_id: string, avatar_id: string, avatar_real_id: number): Promise<SetAvatarResponse>;
+    avatarsCustomize(params: {
+        label_id: number;
+        user_id: number;
+        prompt_id: number;
+        avatar_url: string;
+        avatar_real_id: number;
+    }): Promise<AvatarCustomizeResponse>;
     avatarsGetListT(user_ext_id: string): Promise<TAvatarDefinition[]>;
     avatarsGetCustomizedT(user_ext_id: string): Promise<TAvatarCustomized[]>;
     avatarsGetPromptsT(user_ext_id: string): Promise<TAvatarPrompt[]>;

package/dist/Tournaments/TournamentRegistrationError.d.ts

@@ -1,14 +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 declare 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/dist/WSAPI/WSAPIAvatars.d.ts

@@ -1,5 +1,6 @@
 import { TAvatarDefinition, TAvatarCustomized, TAvatarPrompt, TSetAvatarResult } from './WSAPITypes';
 import { WSAPIMiniGames } from './WSAPIMiniGames';
+import { AvatarCustomizeResponse } from '../Avatars/AvatarCustomizeResponse';
 /** @group Avatars */
 export declare class WSAPIAvatars extends WSAPIMiniGames {
     /**
@@ -293,4 +294,106 @@ export declare class WSAPIAvatars extends WSAPIMiniGames {
         avatar_url: string;
         avatar_real_id: number;
     }): Promise<TSetAvatarResult>;
+    /**
+     * Generates an AI-customized variant of a base avatar by applying an
+     * operator-defined style prompt, returning the CDN URL of the result.
+     * This is a paid, generate-only step: it does NOT change the user's
+     * active avatar — pass the returned `cdn_url` to {@link setAvatar} to
+     * activate it.
+     *
+     * @remarks
+     * **Preconditions**
+     * - Authenticated session required; not available in visitor mode (throws).
+     * - All five fields are mandatory — the SDK throws synchronously
+     *   (`Error("<field> is required")`) if any is missing or zero.
+     * - `prompt_id` must be one of the prompts from {@link getAvatarPrompts};
+     *   `avatar_url` / `avatar_real_id` identify the base avatar to style.
+     *
+     * **Cost**
+     * Each generation costs the currency the operator configured on the
+     * chosen prompt (points, gems, or diamonds — some prompts are free; read
+     * `cost_currency_type_id` / `cost_value` from the {@link getAvatarPrompts}
+     * entry to gate the UI before calling). The cost is charged only on
+     * success; if the user can't afford it the call fails with `errCode -1`
+     * and nothing is generated or charged.
+     *
+     * **Latency**
+     * Generation runs server-side AI image synthesis and is synchronous from
+     * the caller's side — expect several seconds (roughly 5–20 s) before the
+     * promise resolves. There is no SDK cache and no push/subscription; show
+     * a loading state for the full duration and disable the trigger to
+     * prevent duplicate submissions.
+     *
+     * **Result & error codes**
+     * On success the result has `cdn_url` set; on failure it has `errCode` /
+     * `errMessage` set and no `cdn_url`. Branch on `errCode` — the generic
+     * message is fixed text, not cause-specific:
+     * - `12001` (`AvatarCustomizeErrorCode.AVATAR_USER_LIMIT`) — the user hit
+     *   their monthly per-user generation cap. Nothing is generated or charged.
+     * - `12002` (`AvatarCustomizeErrorCode.AVATAR_LABEL_LIMIT`) — the brand's
+     *   shared monthly pool is exhausted. Nothing is generated or charged;
+     *   surface a "try again later" message.
+     * - `-1` — generic failure: insufficient balance, an unavailable prompt,
+     *   or a generation error. Nothing is charged. Allow the user to retry.
+     *
+     * Both monthly caps are operator-configured and reset at the start of
+     * each calendar month.
+     *
+     * **Side effects (on success)**
+     * The generated variant is persisted to the user's customization history
+     * and counts toward the monthly caps **whether or not** it is later
+     * activated — generation is not reversible. The SDK clears the
+     * {@link getAvatarsCustomized} cache so the next call surfaces the new
+     * variant. The user's active avatar is unchanged until you call
+     * {@link setAvatar} with the returned `cdn_url`.
+     *
+     * **Idempotency**: not idempotent — each successful call generates (and
+     * charges for) a new variant. Guard the call site against double-clicks.
+     *
+     * **UI guidance**: see [UI Guide — `avatarsCustomize`](../../docs/ui/avatars/UIGuide_avatarsCustomize.md).
+     *
+     * **Visitor mode**: not supported (throws).
+     *
+     * @param props.label_id        Numeric Smartico label (brand) ID the user belongs to.
+     * @param props.user_id         Numeric Smartico user ID.
+     * @param props.prompt_id       Style-prompt ID (`prompt_id`) from {@link getAvatarPrompts}.
+     * @param props.avatar_url      CDN URL of the base avatar to customize.
+     * @param props.avatar_real_id  `avatar_real_id` of the base avatar.
+     * @returns {@link AvatarCustomizeResponse} — `cdn_url` set on success;
+     *          `errCode` / `errMessage` set on failure.
+     *
+     * @example
+     * ```ts
+     * // label_id / user_id identify the Smartico user being customized.
+     * const prompts = await window._smartico.api.getAvatarPrompts();
+     * const prompt = prompts[0];
+     *
+     * console.log('[smartico] generating avatar — show a spinner for ~5-20s and disable the Generate button');
+     * const result = await window._smartico.api.avatarsCustomize({
+     *   label_id,
+     *   user_id,
+     *   prompt_id: prompt.prompt_id,
+     *   avatar_url: baseAvatar.avatar_url,
+     *   avatar_real_id: baseAvatar.avatar_real_id,
+     * });
+     *
+     * if (result.cdn_url) {
+     *   console.log('[smartico] generation succeeded — preview this URL, then call setAvatar to apply it:', result.cdn_url);
+     *   // await window._smartico.api.setAvatar({ avatar_url: result.cdn_url, avatar_real_id: baseAvatar.avatar_real_id });
+     * } else if (result.errCode === 12001) {
+     *   console.error('[smartico] user monthly limit reached — show "you have used all your custom avatars this month"');
+     * } else if (result.errCode === 12002) {
+     *   console.error('[smartico] brand monthly pool exhausted — show "custom avatars are unavailable right now, try later"');
+     * } else {
+     *   console.error('[smartico] generation failed (e.g. not enough balance) — let the user retry:', result.errMessage);
+     * }
+     * ```
+     */
+    avatarsCustomize(props: {
+        label_id: number;
+        user_id: number;
+        prompt_id: number;
+        avatar_url: string;
+        avatar_real_id: number;
+    }): Promise<AvatarCustomizeResponse>;
 }

package/dist/WSAPI/WSAPIClans.d.ts

@@ -280,12 +280,10 @@ export declare 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/dist/WSAPI/WSAPILeaderBoard.d.ts

@@ -48,15 +48,8 @@ export declare 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
@@ -126,8 +119,7 @@ export declare 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');
      *

package/dist/WSAPI/WSAPIMissions.d.ts

@@ -177,8 +177,14 @@ export declare 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.
      *

package/dist/WSAPI/WSAPITypes.d.ts

@@ -899,6 +899,10 @@ export interface TMissionOrBadgeTask {
     progress: number;
     /** Reward for completing the task in points */
     points_reward: number;
+    /** Reward for completing the task in gems */
+    gems_reward?: number;
+    /** Reward for completing the task in diamonds */
+    diamonds_reward?: number;
     /** This is the total number of times the user needs to execute to complete task. e.g. he needs to bet 100 times. Here will be 100 */
     execution_count_expected?: number;
     /** This is the number of times the user has executed 'activity' of the task. e.g. he bet 5 times out of 100. Here will be 5 */
@@ -1675,9 +1679,9 @@ export interface TAvatarPrompt {
     name: string;
     /** Absolute CDN URL of the prompt's preview icon. */
     icon_url: string;
-    /** Currency used to pay for the customization. `0` = points, `1` = gems, `2` = diamonds. */
+    /** Currency used to pay for the customization. `0` = points, `1` = gems, `2` = diamonds, `3` = free. A `cost_value` of `0` is also free. */
     cost_currency_type_id: number;
-    /** Cost amount in the currency named by `cost_currency_type_id`. */
+    /** Cost amount in the currency named by `cost_currency_type_id`. `0` = free. */
     cost_value: number;
 }
 /**

package/dist/WSAPI/WSAPIUser.d.ts

@@ -334,12 +334,25 @@ export declare 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
@@ -367,10 +380,10 @@ export declare 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);
      *   }
@@ -403,14 +416,12 @@ export declare 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