@smartico/public-api 0.0.386 → 0.0.387

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

@@ -953,6 +953,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 */
@@ -1780,9 +1784,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/tsconfig.json

@@ -90,7 +90,9 @@
 			"src/Tournaments/GetClanTournamentPlayersResponse.ts",
 			"src/Avatars/AvatarDefinition.ts",
 			"src/Avatars/AvatarCustomized.ts",
-			"src/Avatars/AvatarPrompt.ts"
+			"src/Avatars/AvatarPrompt.ts",
+			"src/Avatars/AvatarCustomizeResponse.ts",
+			"src/Avatars/AvatarCustomizeErrorCode.ts"
 		],
 		"out": "docs/api",
 		"projectDocuments": ["docs/SmarticoObject.md", "docs/Callbacks.md", "docs/Transforms.md"],