@smartico/public-api 0.0.385 → 0.0.387

package/docs/native/PROTOCOL.md

@@ -1802,6 +1802,8 @@ Join (or switch to) a clan. On labels with no cooldown, switching clans re-charg
 
 Avatar selection (`setAvatar`) is documented under [User](#setavatar). The methods below read the avatar catalog and the user's AI-customized avatars.
 
+> **Note:** Generating a new AI-customized variant (`avatarsCustomize` in the JS SDK) is a separate **HTTP POST** to the avatar server, not part of this WebSocket protocol. It returns a CDN URL that you then activate via `setAvatar`. Native clients must call that HTTP endpoint directly; it is out of scope for this spec.
+
 ### getAvatarsList
 
 Get the avatar catalog available to the current user.
@@ -1862,7 +1864,7 @@ No method-specific fields. Send only the common fields (see [Common Message Fiel
 |-------|------|-------------|
 | `prompts` | [`AvatarPrompt[]`](../api/interfaces/AvatarPrompt.md) | Available AI style prompts |
 
-> **Note:** Prompt name/icon are nested at `public_meta.name` / `public_meta.icon_url`. `cost_currency_type_id`: `0` = points, `1` = gems, `2` = diamonds; `cost_value` is the amount.
+> **Note:** Prompt name/icon are nested at `public_meta.name` / `public_meta.icon_url`. `cost_currency_type_id`: `0` = points, `1` = gems, `2` = diamonds, `3` = free; `cost_value` is the amount (a `cost_value` of `0` is also free).
 
 ---
 

package/docs/ui/avatars/UIGuide_avatarsCustomize.md

@@ -0,0 +1,69 @@
+# UI Guide — `avatarsCustomize`
+
+## Overview
+- A **paid, generate-only** AI step: it applies an operator-defined style
+  prompt to a base avatar and returns a `cdn_url` for the generated image.
+- It does **not** change the user's active avatar. Activation is a second,
+  explicit step — call `setAvatar({ avatar_url: cdn_url, avatar_real_id })`.
+- Synchronous and slow (~5–20 s). No SDK cache, no push.
+
+## Flow (the default Smartico UI)
+1. **Pick a base avatar** from the avatar catalogue (`getAvatarsList()` /
+   `getAvatarsCustomized()`), then open the "Customize" panel.
+2. **Pick a style prompt** from `getAvatarPrompts()`. Each prompt carries its
+   cost (`cost_currency_type_id` + `cost_value`); render the price on the
+   prompt tile and pre-disable prompts the user can't afford (compare against
+   the balances on `getUserProfile()`).
+3. **Generate.** On tap, call `avatarsCustomize(...)`. Immediately enter a
+   loading state (see below) and lock the prompt list + Generate button.
+4. **Preview.** On success, render `cdn_url` as a preview. The user can keep
+   browsing previously generated variants (they live in the customization
+   history surfaced by `getAvatarsCustomized()`).
+5. **Apply (explicit).** Only when the user taps "Apply" do you call
+   `setAvatar(...)` with the currently-selected URL (which may be the new
+   `cdn_url`, a history item, or the untouched base avatar).
+
+## Loading state
+- The generation blocks for several seconds. Show a spinner/skeleton in the
+  preview slot for the full duration; keep the modal open.
+- Disable the Generate trigger and the prompt list while in flight — there is
+  no SDK-side debounce, so a second tap fires a second (charged) generation.
+
+## Cost gating
+- Read `cost_currency_type_id` (`0` points · `1` gems · `2` diamonds · `3`
+  free) and `cost_value` from the chosen `getAvatarPrompts()` entry.
+- `cost_value === 0` (or type `3`) is free.
+- Gate before calling: if the user can't afford the prompt, disable the tile
+  and show the price; don't rely on the server to be the only guard
+  (insufficient balance comes back as the generic `-1`).
+
+## Error / limit handling
+| Result | UI |
+|---|---|
+| `cdn_url` set | Success. Render the preview; enable "Apply". |
+| `errCode === 12001` | User hit their **monthly per-user cap**. Show e.g. "You've used all your custom avatars this month." Nothing was charged. |
+| `errCode === 12002` | The **brand's monthly pool** is exhausted. Show "Custom avatars are unavailable right now — try again later." Nothing was charged. |
+| `errCode === -1` | Generic failure (insufficient balance, unavailable prompt, generation error). Show a retryable error; nothing was charged. `errMessage` is fixed text — don't surface it as the reason. |
+
+Both monthly caps are operator-configured and reset at the start of each
+calendar month.
+
+## Important behavioral caveats
+- **Generation is irreversible and counts toward the monthly caps on success
+  — even if the user never applies it.** Don't auto-generate on hover/scroll;
+  require an explicit tap.
+- **Apply uses the currently-selected image**, which may be the new variant, a
+  history item, or the base avatar. Track selection explicitly so "Apply"
+  sends the right URL.
+- After a successful generation the SDK refreshes the
+  `getAvatarsCustomized()` cache, so the new variant appears in the history
+  list on the next call.
+
+## Empty / unavailable states
+- No prompts returned by `getAvatarPrompts()` → hide the Customize entry point.
+- `12002` for the whole brand → consider hiding/greying the Customize entry
+  point until next month rather than letting every tap fail.
+
+## Visitor mode
+- Not supported — `avatarsCustomize` throws in visitor mode. Hide the
+  customization surface for unauthenticated sessions.

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.385",
+	"version": "0.0.387",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/src/Avatars/AvatarCustomizeErrorCode.ts

@@ -1,9 +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 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 const AvatarCustomizeErrorMessage: Record<AvatarCustomizeErrorCode, string> = {
-	[AvatarCustomizeErrorCode.AVATAR_USER_LIMIT]: 'You have exceeded number of custom avatars creation, please try later',
-	[AvatarCustomizeErrorCode.AVATAR_LABEL_LIMIT]: 'The custom avatars are not available, please try again later',
-};

package/src/Avatars/AvatarCustomizeResponse.ts

@@ -0,0 +1,17 @@
+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/src/Avatars/index.ts

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

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/Missions/UserAchievement.ts

@@ -123,6 +123,8 @@ export const UserAchievementTransform = (items: UserAchievement[]): TMissionOrBa
 							id: t.task_id,
 							name: t.task_public_meta?.name,
 							points_reward: t.points_reward,
+							gems_reward: t.gems_reward,
+							diamonds_reward: t.diamonds_reward,
 							is_completed: t.isCompleted,
 							progress: t.userProgress,
 							execution_count_expected: t.executionCount,

package/src/Missions/UserAchievementTask.ts

@@ -6,6 +6,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; // 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

package/src/SmarticoAPI.ts

@@ -144,6 +144,7 @@ import { GetAvatarsListResponse, avatarDefinitionTransform } from './Avatars/Get
 import { GetAvatarsCustomizedResponse, avatarCustomizedTransform } from './Avatars/GetAvatarsCustomizedResponse';
 import { GetAvatarPromptsResponse, avatarPromptTransform } from './Avatars/GetAvatarPromptsResponse';
 import { SetAvatarRequest, SetAvatarResponse } from './Avatars';
+import { AvatarCustomizeResponse } from './Avatars/AvatarCustomizeResponse';
 import { GetJackpotWinnersResponse, GetJackpotWinnersResponseTransform, JackpotWinnerHistory } from './Jackpots/GetJackpotWinnersResponse';
 import { GetJackpotWinnersRequest } from './Jackpots/GetJackpotWinnersRequest';
 import { GetJackpotEligibleGamesRequest } from './Jackpots/GetJackpotEligibleGamesRequest';
@@ -183,6 +184,7 @@ class SmarticoAPI {
 	private gamesApiUrl: string;
 	private baseRgApiParams: Record<string, string>;
 	public avatarDomain: string;
+	private avatarOriginDomain: string;
 	private envId: number;
 
 	private logger: ILogger;
@@ -220,6 +222,7 @@ class SmarticoAPI {
 		}
 
 		this.avatarDomain = SmarticoAPI.getAvatarUrl(label_api_key || options.tracker?.label_api_key);
+		this.avatarOriginDomain = SmarticoAPI.getAvatarOriginUrl(label_api_key || options.tracker?.label_api_key);
 
 		this.label_api_key = SmarticoAPI.getCleanLabelApiKey(label_api_key);
 	}
@@ -292,6 +295,10 @@ class SmarticoAPI {
 		return SmarticoAPI.replaceSmrDomainsWithCloudfront(avatarUrl);
 	}
 
+	public static getAvatarOriginUrl(label_api_key: string): string {
+		return AVATAR_DOMAIN.replace('{ENV_ID}', SmarticoAPI.getEnvDnsSuffix(label_api_key));
+	}
+
 	private async send<T>(message: any, expectCID?: ClassId, force_language?: string): Promise<T> {
 		if (this.logCIDs.includes(message.cid)) {
 			this.logger.info('REQ', message);
@@ -1438,6 +1445,31 @@ class SmarticoAPI {
 		}
 	}
 
+	private async sendAvatarApi<T>({ method, body }: { method: string, body: Record<string, any> }): Promise<T> {
+		if (!this.tracker) {
+			throw new Error(`Avatar APIs are not available in the visitor mode`);
+		}
+
+		const url = `${this.avatarOriginDomain}/${method}`;
+
+		try {
+			const response = await fetch(url, {
+				method: 'POST',
+				headers: {
+					'Accept': 'application/json',
+					'Content-Type': 'application/json',
+				},
+				body: JSON.stringify(body),
+			});
+
+			const data = await response.json();
+			return SmarticoAPI.replaceSmrDomainsWithCloudfront<T>(data);
+		} catch (e) {
+			this.logger.error(`Failed to call avatar API: ${method}`, { url, error: e.message });
+			throw new Error(`Failed to call avatar API: ${method}. ${e.message}`);
+		}
+	}
+
 	public async gpGetActiveRounds(saw_template_id: number): Promise<GamesApiResponse<GamePickRound[]>> {
 		const params = {
 			ext_game_id: saw_template_id,
@@ -1539,6 +1571,27 @@ class SmarticoAPI {
 		return await this.send<SetAvatarResponse>(message, ClassId.CLIENT_SET_AVATAR_RESPONSE);
 	}
 
+	public async avatarsCustomize(params: {
+		label_id: number;
+		user_id: number;
+		prompt_id: number;
+		avatar_url: string;
+		avatar_real_id: number;
+	}): Promise<AvatarCustomizeResponse> {
+		return this.sendAvatarApi<AvatarCustomizeResponse>({
+			method: 'avatar-customize',
+			body: {
+				label_id: params.label_id,
+				user_id: params.user_id,
+				user_ext_id: this.tracker?.getExtUserId(),
+				brand_key: this.brand_api_key || this.tracker?.params?.brand_key,
+				prompt_id: params.prompt_id,
+				avatar_url: params.avatar_url,
+				avatar_real_id: params.avatar_real_id,
+			},
+		});
+	}
+
 	public async avatarsGetListT(user_ext_id: string): Promise<TAvatarDefinition[]> {
 		return avatarDefinitionTransform((await this.avatarsGetList(user_ext_id)).avatars ?? [], this.avatarDomain);
 	}

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/WSAPIAvatars.ts

@@ -10,6 +10,7 @@ import {
 	onUpdateContextKey,
 } from './WSAPIBase';
 import { WSAPIMiniGames } from './WSAPIMiniGames';
+import { AvatarCustomizeResponse } from '../Avatars/AvatarCustomizeResponse';
 
 /** @group Avatars */
 export class WSAPIAvatars extends WSAPIMiniGames {
@@ -342,4 +343,124 @@ export class WSAPIAvatars extends WSAPIMiniGames {
 			err_message: r.errMsg,
 		};
 	}
+
+	/**
+	 * 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);
+	 * }
+	 * ```
+	 */
+	public async avatarsCustomize(props: {
+		label_id: number;
+		user_id: number;
+		prompt_id: number;
+		avatar_url: string;
+		avatar_real_id: number;
+	}): Promise<AvatarCustomizeResponse> {
+		const required: (keyof typeof props)[] = ['label_id', 'user_id', 'prompt_id', 'avatar_url', 'avatar_real_id'];
+		for (const field of required) {
+			if (!props[field]) {
+				throw new Error(`${field} is required`);
+			}
+		}
+
+		const r = await this.api.avatarsCustomize(props);
+
+		// On success a new variant is persisted server-side — drop the cached
+		// list so the next getAvatarsCustomized() surfaces it.
+		if (r.cdn_url) {
+			OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.AvatarsCustomized);
+		}
+
+		return r;
+	}
 }

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/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,