@smartico/public-api 0.0.361 → 0.0.363

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smartico/public-api",
-	"version": "0.0.361",
+	"version": "0.0.363",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/src/Avatars/AvatarCustomizeErrorCode.ts

@@ -0,0 +1,9 @@
+export enum AvatarCustomizeErrorCode {
+	AVATAR_USER_LIMIT = 12001,
+	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/AvatarCustomized.ts

@@ -0,0 +1,8 @@
+export interface AvatarCustomized {
+	/** The avatar real id that this customization belongs to */
+	avatar_real_id: number;
+	/** CDN URL of the AI-customized avatar image */
+	url: string;
+	/** ISO date string when the customization was created */
+	dt_created: string;
+}

package/src/Avatars/AvatarDefinition.ts

@@ -0,0 +1,30 @@
+export interface AvatarDefinition {
+	/** Unique identifier of the avatar */
+	avatar_real_id: number;
+	/** Whether this avatar is the default one */
+	is_default: boolean;
+	/** If true, avatar is hidden until user achieves/unlocks it */
+	hide_until_achieved: boolean;
+	/** Display priority — lower value means higher position */
+	priority: number;
+	/** Public metadata containing the avatar image URL and optional description */
+	public_meta: {
+		/** Optional description of the avatar */
+		description?: string;
+		/** Image path/URL of the avatar */
+		url: string;
+	};
+	/**
+	 * Source type of the avatar.
+	 * 0 = free (always available), other values = earned/purchased
+	 */
+	avatar_source_type_id: number;
+	/** ISO date string from which the avatar becomes available */
+	active_from_date?: string;
+	/** ISO date string until which the avatar is available */
+	active_till_date?: string;
+	/** Whether the avatar has been granted/given to the current user */
+	is_given: boolean;
+	/** Whether this avatar is currently in use by the user */
+	is_in_use?: boolean;
+}

package/src/Avatars/AvatarPrompt.ts

@@ -0,0 +1,15 @@
+export interface AvatarPrompt {
+	/** Unique identifier of the AI customization prompt */
+	prompt_id: number;
+	/** Public metadata for the prompt */
+	public_meta: {
+		/** Display name of the prompt style (e.g. "Cartoon", "Watercolor") */
+		name: string;
+		/** URL of the prompt style icon image */
+		icon_url: string;
+	};
+	/** Currency type used to pay for this customization (0=points, 1=gems, 2=diamonds) */
+	cost_currency_type_id: number;
+	/** Cost amount in the given currency */
+	cost_value: number;
+}

package/src/Avatars/GetAvatarPromptsResponse.ts

@@ -0,0 +1,17 @@
+import { TAvatarPrompt } from '../WSAPI/WSAPITypes';
+import { ProtocolResponse } from '../Base/ProtocolResponse';
+import { AvatarPrompt } from './AvatarPrompt';
+
+export interface GetAvatarPromptsResponse extends ProtocolResponse {
+	prompts: AvatarPrompt[];
+}
+
+export const avatarPromptTransform = (items: AvatarPrompt[], avatarDomain: string): TAvatarPrompt[] => {
+	return items.map((item) => ({
+		prompt_id: item.prompt_id,
+		name: item.public_meta.name,
+		icon_url: item.public_meta.icon_url && !item.public_meta.icon_url.startsWith('http') ? `${avatarDomain}${item.public_meta.icon_url}` : item.public_meta.icon_url,
+		cost_currency_type_id: item.cost_currency_type_id,
+		cost_value: item.cost_value,
+	}));
+};

package/src/Avatars/GetAvatarsCustomizedResponse.ts

@@ -0,0 +1,15 @@
+import { TAvatarCustomized } from '../WSAPI/WSAPITypes';
+import { ProtocolResponse } from '../Base/ProtocolResponse';
+import { AvatarCustomized } from './AvatarCustomized';
+
+export interface GetAvatarsCustomizedResponse extends ProtocolResponse {
+	avatars: AvatarCustomized[];
+}
+
+export const avatarCustomizedTransform = (items: AvatarCustomized[], avatarDomain: string): TAvatarCustomized[] => {
+	return items.map((item) => ({
+		avatar_real_id: item.avatar_real_id,
+		url: item.url && !item.url.startsWith('http') ? `${avatarDomain}${item.url}` : item.url,
+		dt_created: item.dt_created,
+	}));
+};

package/src/Avatars/GetAvatarsListResponse.ts

@@ -0,0 +1,24 @@
+import { TAvatarDefinition } from '../WSAPI/WSAPITypes';
+import { ProtocolResponse } from '../Base/ProtocolResponse';
+import { AvatarDefinition } from './AvatarDefinition';
+
+export interface GetAvatarsListResponse extends ProtocolResponse {
+	avatars: AvatarDefinition[];
+}
+
+export const avatarDefinitionTransform = (items: AvatarDefinition[], avatarDomain: string): TAvatarDefinition[] => {
+	return items.map((item) => ({
+		avatar_real_id: item.avatar_real_id,
+		is_default: item.is_default,
+		hide_until_achieved: item.hide_until_achieved,
+		priority: item.priority,
+		description: item.public_meta.description,
+		url: item.public_meta.url,
+		avatar_url: item.public_meta.url && !item.public_meta.url.startsWith('http') ? `${avatarDomain}${item.public_meta.url}` : item.public_meta.url,
+		avatar_source_type_id: item.avatar_source_type_id,
+		active_from_date: item.active_from_date,
+		active_till_date: item.active_till_date,
+		is_given: item.is_given,
+		is_in_use: item.is_in_use,
+	}));
+};

package/src/Avatars/SetAvatarRequest.ts

@@ -0,0 +1,8 @@
+import { ProtocolRequest } from '../Base/ProtocolRequest';
+
+export interface SetAvatarRequest extends ProtocolRequest {
+	/** The avatar image URL or path to set */
+	avatar_id: string;
+	/** The avatar_real_id from the avatar catalog */
+	avatar_real_id: number;
+}

package/src/Avatars/SetAvatarResponse.ts

@@ -0,0 +1,6 @@
+import { ProtocolResponse } from '../Base/ProtocolResponse';
+
+export interface SetAvatarResponse extends ProtocolResponse {
+	/** The resolved avatar URL after applying the avatar */
+	avatar_id: string;
+}

package/src/Avatars/index.ts

@@ -0,0 +1,9 @@
+export * from './AvatarCustomizeErrorCode';
+export * from './AvatarDefinition';
+export * from './AvatarCustomized';
+export * from './AvatarPrompt';
+export * from './GetAvatarsListResponse';
+export * from './GetAvatarsCustomizedResponse';
+export * from './GetAvatarPromptsResponse';
+export * from './SetAvatarRequest';
+export * from './SetAvatarResponse';

package/src/SmarticoAPI.ts

@@ -100,6 +100,9 @@ import {
 	TLevelCurrent,
 	TActivityLog,
 	TRaffleDraw,
+	TAvatarDefinition,
+	TAvatarCustomized,
+	TAvatarPrompt,
 } from './WSAPI/WSAPITypes';
 import { getLeaderBoardTransform } from './Leaderboard/LeaderBoards';
 import { GetAchievementsUserInfoResponse } from './Core/GetAchievementsUserInfoResponse';
@@ -129,6 +132,10 @@ import { GetRafflesRequest } from './Raffle/GetRafflesRequest';
 import { GetActivityLogRequest, GetActivityLogResponse, ActivityLogTransform } from './ActivityLog';
 import { InboxCategories } from './Inbox/InboxCategories';
 import { GetDrawRunRequest, GetDrawRunResponse, GetRaffleDrawRunsHistoryRequest, GetRaffleDrawRunsHistoryResponse, RaffleClaimPrizeRequest, RaffleClaimPrizeResponse, RaffleOptinRequest, RaffleOptinResponse, drawRunTransform } from './Raffle';
+import { GetAvatarsListResponse, avatarDefinitionTransform } from './Avatars/GetAvatarsListResponse';
+import { GetAvatarsCustomizedResponse, avatarCustomizedTransform } from './Avatars/GetAvatarsCustomizedResponse';
+import { GetAvatarPromptsResponse, avatarPromptTransform } from './Avatars/GetAvatarPromptsResponse';
+import { SetAvatarRequest, SetAvatarResponse } from './Avatars';
 import { GetJackpotWinnersResponse, GetJackpotWinnersResponseTransform, JackpotWinnerHistory } from './Jackpots/GetJackpotWinnersResponse';
 import { GetJackpotWinnersRequest } from './Jackpots/GetJackpotWinnersRequest';
 import { GetJackpotEligibleGamesRequest } from './Jackpots/GetJackpotEligibleGamesRequest';
@@ -1419,6 +1426,41 @@ class SmarticoAPI {
 		return this.sendGamesApi<GamePickRound>({ method: 'game-round-info-for-user', params });
 	}
 
+	public async avatarsGetList(user_ext_id: string): Promise<GetAvatarsListResponse> {
+		const message = this.buildMessage<any, GetAvatarsListResponse>(user_ext_id, ClassId.GET_AVATARS_LIST_REQUEST);
+		return await this.send<GetAvatarsListResponse>(message, ClassId.GET_AVATARS_LIST_RESPONSE);
+	}
+
+	public async avatarsGetCustomized(user_ext_id: string): Promise<GetAvatarsCustomizedResponse> {
+		const message = this.buildMessage<any, GetAvatarsCustomizedResponse>(user_ext_id, ClassId.GET_AVATARS_CUSTOMIZED_REQUEST);
+		return await this.send<GetAvatarsCustomizedResponse>(message, ClassId.GET_AVATARS_CUSTOMIZED_RESPONSE);
+	}
+
+	public async avatarsGetPrompts(user_ext_id: string): Promise<GetAvatarPromptsResponse> {
+		const message = this.buildMessage<any, GetAvatarPromptsResponse>(user_ext_id, ClassId.GET_AVATAR_PROMPTS_REQUEST);
+		return await this.send<GetAvatarPromptsResponse>(message, ClassId.GET_AVATAR_PROMPTS_RESPONSE);
+	}
+
+	public async avatarSetAvatar(user_ext_id: string, avatar_id: string, avatar_real_id: number): Promise<SetAvatarResponse> {
+		const message = this.buildMessage<SetAvatarRequest, SetAvatarResponse>(user_ext_id, ClassId.CLIENT_SET_AVATAR_REQUEST, {
+			avatar_id,
+			avatar_real_id,
+		});
+		return await this.send<SetAvatarResponse>(message, ClassId.CLIENT_SET_AVATAR_RESPONSE);
+	}
+
+	public async avatarsGetListT(user_ext_id: string): Promise<TAvatarDefinition[]> {
+		return avatarDefinitionTransform((await this.avatarsGetList(user_ext_id)).avatars ?? [], this.avatarDomain);
+	}
+
+	public async avatarsGetCustomizedT(user_ext_id: string): Promise<TAvatarCustomized[]> {
+		return avatarCustomizedTransform((await this.avatarsGetCustomized(user_ext_id)).avatars ?? [], this.avatarDomain);
+	}
+
+	public async avatarsGetPromptsT(user_ext_id: string): Promise<TAvatarPrompt[]> {
+		return avatarPromptTransform((await this.avatarsGetPrompts(user_ext_id)).prompts ?? [], this.avatarDomain);
+	}
+
 	public getWSCalls(): WSAPI {
 		return new WSAPI(this);
 	}

package/src/WSAPI/WSAPI.ts

@@ -46,6 +46,10 @@ import {
 	GamePickGameInfo,
 	GamePickRequestParams,
 	GamePickRoundRequestParams,
+	TAvatarDefinition,
+	TAvatarCustomized,
+	TAvatarPrompt,
+	TSetAvatarResult,
 } from './WSAPITypes';
 import { LeaderBoardPeriodType } from '../Leaderboard';
 import {
@@ -103,6 +107,9 @@ enum onUpdateContextKey {
 	CurrentLevel = 'currentLevel',
 	InboxUnreadCount = 'inboxUnreadCount',
 	ActivityLog = 'activityLog',
+	AvatarsList = 'avatarsList',
+	AvatarsCustomized = 'avatarsCustomized',
+	AvatarPrompts = 'avatarPrompts',
 }
 
 /** @group General API */
@@ -1445,6 +1452,118 @@ export class WSAPI {
 		return this.api.gpGetRoundInfoForUser(props.saw_template_id, props.round_id, props.int_user_id);
 	}
 
+	/**
+	 * Returns the list of avatars available in the catalog for the current user.
+	 * The response includes both free avatars and earned/purchased ones.
+	 * Avatars with `hide_until_achieved = true` and `is_given = false` should be hidden from the user.
+	 * The result is cached for 30 seconds.
+	 *
+	 * **Example**:
+	 * ```
+	 * _smartico.api.getAvatarsList().then((result) => {
+	 *      console.log(result);
+	 * });
+	 * ```
+	 *
+	 * **Visitor mode: not supported**
+	 */
+	public async getAvatarsList(): Promise<TAvatarDefinition[]> {
+		return OCache.use(
+			onUpdateContextKey.AvatarsList,
+			ECacheContext.WSAPI,
+			() => this.api.avatarsGetListT(this.userExtId),
+			CACHE_DATA_SEC,
+		);
+	}
+
+	/**
+	 * Returns the list of AI-customized avatars for the current user.
+	 * Each entry represents a previously generated AI customization for a specific base avatar.
+	 * The result is cached for 30 seconds.
+	 *
+	 * **Example**:
+	 * ```
+	 * _smartico.api.getAvatarsCustomized().then((result) => {
+	 *      console.log(result);
+	 * });
+	 * ```
+	 *
+	 * **Visitor mode: not supported**
+	 */
+	public async getAvatarsCustomized(): Promise<TAvatarCustomized[]> {
+		return OCache.use(
+			onUpdateContextKey.AvatarsCustomized,
+			ECacheContext.WSAPI,
+			() => this.api.avatarsGetCustomizedT(this.userExtId),
+			CACHE_DATA_SEC,
+		);
+	}
+
+	/**
+	 * Returns the list of AI customization prompts (styles) available for avatar customization.
+	 * Each prompt represents a visual style that can be applied to a base avatar.
+	 * The result is cached for 30 seconds.
+	 *
+	 * **Example**:
+	 * ```
+	 * _smartico.api.getAvatarPrompts().then((result) => {
+	 *      console.log(result);
+	 * });
+	 * ```
+	 *
+	 * **Visitor mode: not supported**
+	 */
+	public async getAvatarPrompts(): Promise<TAvatarPrompt[]> {
+		return OCache.use(
+			onUpdateContextKey.AvatarPrompts,
+			ECacheContext.WSAPI,
+			() => this.api.avatarsGetPromptsT(this.userExtId),
+			CACHE_DATA_SEC,
+		);
+	}
+
+	/**
+	 * Sets the specified avatar as the active avatar for the current user.
+	 * Pass `avatar_url` (the `TAvatarDefinition.url` path or a CDN URL for AI-customized avatars)
+	 * and `avatar_real_id` from the avatar catalog.
+	 * After a successful call, the avatar list cache is cleared so the next `getAvatarsList()` call reflects `is_in_use`.
+	 *
+	 * **Example**:
+	 * ```
+	 * _smartico.api.getAvatarsList().then((avatars) => {
+	 *      const avatar = avatars.find((a) => !a.hide_until_achieved || a.is_given);
+	 *      if (avatar) {
+	 *          _smartico.api.setAvatar({
+	 *              avatar_url: avatar.url,
+	 *              avatar_real_id: avatar.avatar_real_id,
+	 *          }).then((result) => {
+	 *              console.log(result);
+	 *          });
+	 *      }
+	 * });
+	 * ```
+	 *
+	 * **Visitor mode: not supported**
+	 */
+	public async setAvatar(props: { avatar_url: string; avatar_real_id: number }): Promise<TSetAvatarResult> {
+		if (!props.avatar_url) {
+			throw new Error('avatar_url is required');
+		}
+		if (!props.avatar_real_id) {
+			throw new Error('avatar_real_id is required');
+		}
+
+		const r = await this.api.avatarSetAvatar(this.userExtId, props.avatar_url, props.avatar_real_id);
+
+		OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.AvatarsList);
+		OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.AvatarsCustomized);
+
+		return {
+			err_code: r.errCode ?? 0,
+			err_message: r.errMsg,
+		};
+	}
+
 	private async updateOnSpin(data: SAWSpinsCountPush) {
 		const templates: TMiniGameTemplate[] = await OCache.use(
 			onUpdateContextKey.Saw,

package/src/WSAPI/WSAPITypes.ts

@@ -1880,4 +1880,77 @@ export interface GamePickRoundRequestParams extends GamePickRequestParams {
 	round_id: number;
 }
 
+/**
+ * TAvatarDefinition describes a single avatar available in the avatar catalog.
+ * Fields from the raw `public_meta` object are flattened to the top level.
+ */
+export interface TAvatarDefinition {
+	/** Unique identifier of the avatar */
+	avatar_real_id: number;
+	/** Whether this avatar is the default one */
+	is_default: boolean;
+	/** If true, avatar is hidden until user achieves/unlocks it */
+	hide_until_achieved: boolean;
+	/** Display priority — lower value means higher position in the grid */
+	priority: number;
+	/** Optional description of the avatar (from public_meta) */
+	description?: string;
+	/** Raw image path/URL of the avatar as returned by the server (from public_meta) */
+	url: string;
+	/** Full CDN URL of the avatar image, built from avatar_domain + url */
+	avatar_url: string;
+	/**
+	 * Source type of the avatar.
+	 * 0 = free (always available to all users), other values = earned/purchased
+	 */
+	avatar_source_type_id: number;
+	/** ISO date string from which the avatar becomes available */
+	active_from_date?: string;
+	/** ISO date string until which the avatar is available */
+	active_till_date?: string;
+	/** Whether the avatar has been granted/given to the current user */
+	is_given: boolean;
+	/** Whether this avatar is currently in use by the user */
+	is_in_use?: boolean;
+}
+
+/**
+ * TAvatarCustomized describes an AI-customized version of a base avatar
+ */
+export interface TAvatarCustomized {
+	/** The avatar_real_id of the base avatar this customization was generated from */
+	avatar_real_id: number;
+	/** Full CDN URL of the AI-generated customized avatar image */
+	url: string;
+	/** ISO date string when the customization was created */
+	dt_created: string;
+}
+
+/**
+ * TAvatarPrompt describes an AI style prompt available for avatar customization.
+ * Fields from the raw `public_meta` object are flattened to the top level.
+ */
+export interface TAvatarPrompt {
+	/** Unique identifier of the AI customization prompt */
+	prompt_id: number;
+	/** Display name of the prompt style, e.g. "Cartoon", "Watercolor" (from public_meta) */
+	name: string;
+	/** Full CDN URL of the prompt style icon image (from public_meta) */
+	icon_url: string;
+	/** Currency type used to pay for this customization (0=points, 1=gems, 2=diamonds) */
+	cost_currency_type_id: number;
+	/** Cost amount in the given currency */
+	cost_value: number;
+}
+
+/**
+ * TSetAvatarResult describes the response of call to _smartico.api.setAvatar() method
+ */
+export interface TSetAvatarResult {
+	/** Error code that represents outcome of the set avatar request. Successful if err_code is 0 */
+	err_code: number;
+	/** Optional error message */
+	err_message?: string;
+}
+
 export { SAWAcknowledgeTypeName, PrizeModifiers, SAWTemplateUI, InboxCategories, AchCustomSectionType, SAWAskForUsername, SAWGameLayout, PointChangeSourceType, UserBalanceType, SAWGPMarketType, QuizAnswersValueType }

package/src/index.ts

@@ -22,4 +22,5 @@ export * from './OCache';
 export * from './Bonuses';
 export * from './CustomSections';
 export * from './ActivityLog';
-export * from './Base/AchRelatedGame';
+export * from './Base/AchRelatedGame';
+export * from './Avatars';