@smartico/public-api 0.0.386 → 0.0.388

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).
 
 ---
 
@@ -1870,7 +1872,8 @@ No method-specific fields. Send only the common fields (see [Common Message Fiel
 
 ### getLeaderBoard
 
-Get leaderboard for a specific period type.
+Get one period's leaderboard with its ranked players, or the list of all
+configured boards without players.
 
 #### Request
 
@@ -1878,9 +1881,14 @@ Get leaderboard for a specific period type.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `period_type_id` | `number` | Period type: `1` = Daily, `2` = Weekly, `3` = Monthly (optional, if not set returns all boards) |
+| `period_type_id` | `number` | Period type: `1` = Daily, `2` = Weekly, `3` = Monthly. Optional — if omitted, the response `map` contains **every** configured board. |
 | `snapshot_offset` | `number` | `0` = current period, `1` = previous period, `2` = period before previous, etc. |
-| `include_users` | `boolean` | Whether to include user details (optional) |
+| `include_users` | `boolean` | `true` → each board includes its `positions` (and `userPosition`). `false` (or omitted) → board metadata only, no players — the lightweight "list available boards" mode. |
+
+> **Two modes from one request.** Send `period_type_id` + `include_users: true`
+> to load a single board's standings. Omit `period_type_id` and send
+> `include_users: false` to enumerate all configured boards (metadata only) —
+> useful to build the board/tab selector before loading any standings.
 
 #### Response
 
@@ -1888,9 +1896,31 @@ Get leaderboard for a specific period type.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `leaders` | [`LeaderBoardUserT[]`](../api/interfaces/LeaderBoardUserT.md) | Array of leaderboard entries |
-| `user_position` | `number` | Current user's position |
-| `user_points` | `number` | Current user's points |
+| `map` | `object` | Keyed by `period_type_id` (as a string: `"1"` / `"2"` / `"3"`), one entry per board. With `period_type_id` set in the request only that key is present; omitted → every configured board. |
+
+Each value of `map` is a leaderboard object:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `board_id` | `number` | Stable board id |
+| `period_type_id` | `number` | `1` = Daily, `2` = Weekly, `3` = Monthly |
+| `create_date` | `number` | `0` for the current period; the snapshot timestamp for a previous period |
+| `versiod_id` | `number` | Snapshot version; `0` for the current period (the field is spelled `versiod_id` on the wire) |
+| `reward_points` | `number[]` | Per-place prize points; index `0` = place 1 |
+| `board_public_meta` | `object` | `{ name, description, rules }` display strings (HTML allowed in `description` / `rules`) |
+| `positions` | `LeaderBoardPosition[]` | Ranked entries, top 20, ordered by rank. **Absent when `include_users` is `false`.** |
+| `userPosition` | `LeaderBoardPosition` | The requesting user's own entry. Absent when `include_users` is `false`, or when the user is unranked. |
+
+Each `LeaderBoardPosition`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `position_in_board` | `number` | Rank (DENSE_RANK); `-1` on `userPosition` = unranked / outside the window |
+| `points_accumulated` | `number` | Participant's points for the period |
+| `public_username` | `string` | Display name (falls back to `user_alt_name`) |
+| `is_me` | `boolean` | `true` for the requesting user's row inside `positions` |
+| `avatar_id` | `string` | Raw avatar id — build the image URL client-side |
+| `level_id` | `number` | The participant's level (factor it into avatar resolution to match the default Smartico UI) |
 
 ---
 

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/leaderboard/UIGuide_getLeaderBoard.md

@@ -9,6 +9,15 @@
 - No subscription, no push refresh. Poll manually if the consumer
   needs live updates during an in-progress period.
 
+## Discovering boards (`getLeaderBoards`)
+Before loading any standings, call `getLeaderBoards()` to discover which
+boards the operator configured (DAILY / WEEKLY / MONTHLY, or none). It
+returns the board list as **metadata only** — `name`, `period_type_id`,
+`rewards`, etc., with `users` empty and `me` undefined — in one lightweight
+round-trip. Build the board/tab selector from that list, then call
+`getLeaderBoard(period_type_id)` to load a tab's standings on demand. If it
+returns an empty array, hide the leaderboard surface entirely.
+
 ## List view organization
 
 The default Smartico UI renders the leaderboard with three top-level
@@ -113,6 +122,12 @@ 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.
 
+To page back through **older** snapshots (not just the immediately
+previous one), pass a number instead of a boolean: `getLeaderBoard(periodType, 2)`
+fetches the period before last, `3` the one before that, etc. Label each
+historical board with its `create_date` / `version_id` so the user knows
+which run they're viewing.
+
 ## Status-specific visual treatments
 
 - **Current period**: full-color rendering; live point counts.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smartico/public-api",
-	"version": "0.0.386",
+	"version": "0.0.388",
 	"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/CustomSections/AchCustomSection.ts

@@ -48,4 +48,5 @@ export enum LiquidEntityData {
 	Tournament = 10,
 	Raffles = 11,
 	SingleRaffle = 12,
+	Clans = 13,
 }

package/src/Leaderboard/LeaderBoards.ts

@@ -13,19 +13,16 @@ const pointsRewardTransform = (reward_points: number[]): LeaderBoardsRewardsT[]
 
 const getLeaderBoardPlayerTransformed = (user: LeaderBoardPosition, isMe?: boolean): LeaderBoardUserT => {
 	if (user) {
-		const x: LeaderBoardUserT = {
+		return {
 			public_username: user?.public_username || user.user_alt_name,
 			avatar_url: user.avatar_url,
+			level_id: user.level_id,
 			position: user.position_in_board,
 			points: user.points_accumulated,
-			is_me: user.is_me,
+			// The `me` entry is the current user by definition, so force `true`
+			// there; list rows carry the server-provided flag.
+			is_me: isMe ? true : user.is_me,
 		};
-
-		if (isMe) {
-			delete x.is_me;
-		}
-
-		return x;
 	}
 
 	return null;
@@ -33,18 +30,18 @@ const getLeaderBoardPlayerTransformed = (user: LeaderBoardPosition, isMe?: boole
 
 export const getLeaderBoardTransform = (board: LeaderBoardDetails): LeaderBoardDetailsT => {
 	if (board) {
-		const x: LeaderBoardDetailsT = {
+		return {
 			board_id: board.board_id,
 			name: board.board_public_meta.name,
 			description: board.board_public_meta.description,
 			rules: board.board_public_meta.rules,
 			period_type_id: board.period_type_id,
+			version_id: board.versiod_id,
+			create_date: board.create_date,
 			rewards: pointsRewardTransform(board.reward_points),
-			users: board.positions.map((p) => getLeaderBoardPlayerTransformed(p)),
+			users: (board.positions || []).map((p) => getLeaderBoardPlayerTransformed(p)),
 			me: getLeaderBoardPlayerTransformed(board.userPosition, true),
 		};
-
-		return x;
 	}
 
 	return null;

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);
@@ -1137,15 +1144,18 @@ class SmarticoAPI {
 	public async leaderboardGet(
 		user_ext_id: string,
 		period_type_id?: LeaderBoardPeriodType,
-		prevPeriod: boolean = false,
+		prevPeriod: boolean | number = false,
 		force_language?: string,
 	): Promise<LeaderBoardDetails> {
+		// boolean keeps back-compat (false → current, true → previous);
+		// a number selects an arbitrary snapshot offset (1 = previous, 2 = the one before, …).
+		const snapshot_offset = typeof prevPeriod === 'number' ? prevPeriod : prevPeriod ? 1 : 0;
 		const message = this.buildMessage<GetLeaderBoardsRequest, GetLeaderBoardsResponse>(
 			user_ext_id,
 			ClassId.GET_LEADERS_BOARD_REQUEST,
 			{
 				period_type_id,
-				snapshot_offset: prevPeriod ? 1 : 0,
+				snapshot_offset,
 				include_users: true,
 			},
 		);
@@ -1177,11 +1187,36 @@ class SmarticoAPI {
 	public async leaderboardsGetT(
 		user_ext_id: string,
 		period_type_id: LeaderBoardPeriodType = LeaderBoardPeriodType.DAILY,
-		prevPeriod: boolean = false,
+		prevPeriod: boolean | number = false,
 	): Promise<LeaderBoardDetailsT> {
 		return getLeaderBoardTransform(await this.leaderboardGet(user_ext_id, period_type_id, prevPeriod));
 	}
 
+	public async leaderboardsGetList(
+		user_ext_id: string,
+		force_language?: string,
+	): Promise<LeaderBoardDetails[]> {
+		const message = this.buildMessage<GetLeaderBoardsRequest, GetLeaderBoardsResponse>(
+			user_ext_id,
+			ClassId.GET_LEADERS_BOARD_REQUEST,
+			{
+				// No period_type_id → the server returns every configured board.
+				// include_users: false → board metadata only (no positions / userPosition).
+				snapshot_offset: 0,
+				include_users: false,
+			},
+		);
+
+		const response = await this.send<GetLeaderBoardsResponse>(message, ClassId.GET_LEADERS_BOARD_RESPONSE, force_language);
+
+		// map is keyed by period_type_id; integer-like keys iterate in ascending order.
+		return Object.values(response.map || {});
+	}
+
+	public async leaderboardsGetListT(user_ext_id: string): Promise<LeaderBoardDetailsT[]> {
+		return (await this.leaderboardsGetList(user_ext_id)).map(getLeaderBoardTransform);
+	}
+
 	public async levelsGet(user_ext_id: string, force_language?: string): Promise<GetLevelMapResponse> {
 		const message = this.buildMessage<any, GetLevelMapResponse>(user_ext_id, ClassId.GET_LEVEL_MAP_REQUEST);
 		return await this.send<GetLevelMapResponse>(message, ClassId.GET_LEVEL_MAP_RESPONSE, force_language);
@@ -1438,6 +1473,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 +1599,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/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;
+	}
 }