@smartico/public-api 0.0.379 → 0.0.381

package/src/WSAPI/WSAPITypes.ts

@@ -88,30 +88,43 @@ export interface TMiniGamePrize {
 }
 
 /**
- * TMiniGamePlayResult describes the response of call to _smartico.api.playMiniGame(template_id) method
+ * TMiniGamePlayResult describes the response of
+ * `_smartico.api.playMiniGame(template_id)`.
  */
 export interface TMiniGamePlayResult {
-	/** Error code that represents outcome of the game play attempt. Game succeed to be played in case err_code is 0 */
+	/** Error code. `0` = success ({@link SAWSpinErrorCode.SAW_OK}).
+	 * See `playMiniGame` TSDoc for the full table. */
 	err_code: SAWSpinErrorCode;
-	/** Optional error message */
+	/** Optional server-side error message. Present only on non-zero
+	 * `err_code`; may be empty even then. */
 	err_message: string;
-	/** The prize_id that user won, details of the prize can be found in the mini-game definition */
+	/** ID of the won prize. Look up in `template.prizes` to interpret
+	 * (including `prize_type === 'no-prize'` for a configured loss
+	 * slot). Always populated, even when `err_code !== 0`. */
 	prize_id: number;
 }
 
 /**
- * TMiniGamePlayBatchResult describes the response of call to _smartico.api.playMiniGameBatch(template_id, spin_count) method
+ * TMiniGamePlayBatchResult describes one entry in the array returned
+ * by `_smartico.api.playMiniGameBatch(template_id, spin_count)`.
+ *
+ * Note: this type uses `errCode` / `errMessage` (camelCase) —
+ * different from `TMiniGamePlayResult` which uses `err_code` /
+ * `err_message` (snake_case).
  */
 export interface TMiniGamePlayBatchResult {
-	/** The saw_prize_id that user won, details of the prize can be found in the mini-game definition */
+	/** ID of the won prize for this spin. Look up in `template.prizes`. */
 	saw_prize_id: number;
-	/** Error code that represents outcome of the game play attempt. Game succeed to be played in case err_code is 0 */
+	/** Error code. `0` = success. See `playMiniGameBatch` TSDoc for the
+	 * full table. */
 	errCode: SAWSpinErrorCode;
-	/** Optional error message */
+	/** Optional server-side error message. */
 	errMessage?: string;
-	/** Jackpot amount what user won */
+	/** Jackpot amount the user won, populated when the prize type is
+	 * `'jackpot'`. */
 	jackpot_amount?: number;
-	/** Period in miliseconds from last spin */
+	/** Epoch ms of the user's first spin in the current cooldown
+	 * period; populated when `errCode === SAWSpinErrorCode.SAW_FAILED_MAX_SPINS_REACHED`. */
 	first_spin_in_period?: number,
 }
 
@@ -212,89 +225,78 @@ export interface TMiniGameTemplate {
  */
 
 export interface TUserProfile {
-	/** The language of the user */
+	/** Language code stored server-side for the user (e.g. `"en"`, `"de"`). */
 	core_user_language: string;
-	/** The current points balance that user can use in the Store, Mini-games, Tournaments, etc.. */
+	/** Current spendable points balance — decremented by store purchases,
+	 * tournament buy-ins, and clan entry fees. */
 	ach_points_balance: number;
-	/** The amount of points that user collected in total */
+	/** All-time cumulative points earned. Monotonic — NOT decremented by
+	 * store purchases or clan/tournament fees. */
 	ach_points_ever: number;
-	/** The current gems balance */
+	/** Current gems balance (secondary currency). */
 	ach_gems_balance: number;
-	/** The current diamonds balance */
+	/** Current diamonds balance (tertiary currency). */
 	ach_diamonds_balance: number;
-	/**
-	 * The array of the public tags set on the user object.
-	 * They can be treated as server-based cookies.
-	 * You can set tags using following method _smartico.event('core_public_tags_update', { core_public_tags: ['A', 'B'] } );
-	 * And then you can check for the tags
-	 */
+	/** Server-stored public tags on the user (uppercase strings).
+	 * Modify via `_smartico.updatePublicTags(operation, tags)`. */
 	core_public_tags: string[];
-	/** The ID of the current level of the user */
+	/** FK into the level ladder; resolve via `getCurrentLevel()` or `getLevels()`. */
 	ach_level_current_id?: number;
-	/** The indicator if user is marked as test user */
+	/** `true` when the user is flagged as a test account. */
 	core_is_test_account?: boolean;
-	/** The URL to the user avatar */
+	/** Resolved CDN URL for the user's avatar. */
 	avatar_url?: string;
-	/** The username of current user */
+	/** Display username (operator-defined alias). */
 	public_username?: string;
-	/** THe number of unread inbox messages */
+	/** Unread inbox messages count. Push-updated in real time. */
 	core_inbox_unread_count?: number;
-	/** The recommended deposit amount for the user */
+	/** AI-recommended deposit amount for this user. Undefined when no
+	 * recommendation is currently available. */
 	core_recommended_deposit_amount?: number;
-	/** The recommended casino bet amount for the user */
+	/** AI-recommended casino bet amount for this user. Undefined when no
+	 * recommendation is currently available. */
 	core_recommended_casino_bet_amount?: number;
 }
 
 /**
- * TLevel describes the information of each level defined in the system
- * There is no order of the levels, but it can be calculated using required_points property
- * The current level of user can be taken from the user object using ach_level_current_id property
- * The progress to the next level can be calculated using ach_points_ever and required_points properties of next level
+ * TLevel describes one level in the label's level ladder.
+ * Returned by `_smartico.api.getLevels()` (already sorted by `required_points` ASC).
  */
 export interface TLevel {
-	/** The ID of the Level */
+	/** Stable ID of the level. */
 	id: number;
-	/** The name of the Level, translated to the user language */
+	/** Display name of the level, pre-translated to the user's language. */
 	name: string;
-	/** The description of the Level, translated to the user language */
+	/** Display description of the level, pre-translated to the user's language. */
 	description: string;
-	/** The URL of the image of the Level, 256x256px */
+	/** URL of the level image (256x256 px source). */
 	image: string;
-	/** The amount of points required to reach the Level */
+	/** Total `ach_points_ever` required to reach this level. */
 	required_points: number;
-	/** Number of points that user should collect in order to see this level */
+	/** Visibility threshold — clients hide the level from the user until
+	 * `ach_points_ever >= visibility_points`. `null` means always visible. */
 	visibility_points: number;
-	/**
-	 * The counter of 1st metric used to reach the Level.
-	 * Relevant in case of using advanced leveling logic
-	 * https://help.smartico.ai/welcome/more/release-notes/september-2022#new-logic-for-leveling-users
-	 *
-	 */
+	/** Required value of the first level counter for sliding-window leveling.
+	 * `null` on points-only labels. See `UserLevelExtraCountersT`. */
 	required_level_counter_1: number;
-	/**
-	 * The counter of 2nd metric used to reach the Level.
-	 * Relevant in case of using advanced leveling logic
-	 * https://help.smartico.ai/welcome/more/release-notes/september-2022#new-logic-for-leveling-users
-	 *
-	 */
+	/** Required value of the second level counter for sliding-window leveling.
+	 * `null` on points-only labels. */
 	required_level_counter_2: number;
-
-	/** 
-	 * Custom data as string or JSON string that can be used in API to build custom UI
-	 * You can request from Smartico to define fields for your specific case that will be managed from Smartico BackOffice
-	 * Read more here - https://help.smartico.ai/welcome/products/general-concepts/custom-fields-attributes
-	 */
+	/** Operator-defined custom data. The SDK auto-parses JSON-looking
+	 * strings, so at runtime this is `any` despite the `string` type. */
 	custom_data: string;
-	/** The ordinal position of the level */
+	/** 1-based position in the ladder (matches the order of the returned
+	 * array, which is sorted by `required_points` ASC). */
 	ordinal_position: number;
 }
 
 /**
- * TLevelCurrent describes the information of each level defined in the system along with ordinal position and progress of the current level
+ * TLevelCurrent extends `TLevel` with the user's progress toward the next level.
+ * Returned by `_smartico.api.getCurrentLevel()`.
  */
-
 export interface TLevelCurrent extends TLevel {
-	/** The progress of the user towards next level in the percents to complete */
+	/** Progress to the next level as a 0–100 integer percentage. `100`
+	 * at the highest level. */
 	progress: number;
 }
 
@@ -326,7 +328,7 @@ export interface TTournament {
 	segment_dont_match_message: string;
 	/**
 	 * The ID of the custom section where the tournament is assigned
-	 * The list of custom sections can be retrieved using _smartico.api.getCustomSections() method (TODO-API)
+	 * The list of custom sections can be retrieved using _smartico.api.getCustomSections() method
 	 */
 	custom_section_id: number;
 	/** The custom data of the tournament defined by operator. Can be a JSON object, string or number */
@@ -557,13 +559,17 @@ export interface TClan {
 	member_count: number;
 	/** Max number of members allowed in clan */
 	capacity_limit: number;
-	/** ShopPurchaseType: 0=Points, 1=Gems, 2=Diamonds, 3=Free */
+	/** Currency type for `entry_fee_amount`. `0` = points, `1` = gems,
+	 * `2` = diamonds, `3` = free (no fee). */
 	entry_fee_currency_type_id: number;
-	/** Numeric value for entry fee */
+	/** Entry fee amount in the currency indicated by `entry_fee_currency_type_id`.
+	 * `0` (or `entry_fee_currency_type_id === 3`) means the clan is free to join. */
 	entry_fee_amount: number;
-	/** F1 rank ASC, 1=best */
+	/** Global rank among all active clans in the label, by `rating_score` DESC.
+	 * `1` = highest-rated. May skip positions when some clans are hidden by
+	 * per-user visibility (e.g. user sees positions 1, 3, 7). */
 	rating_position: number;
-	/** Clan rating score */
+	/** Clan rating score (higher is better). */
 	rating_score: number;
 }
 
@@ -575,7 +581,9 @@ export interface TClans {
 	clans: TClan[];
 	/** The clan ID the current user belongs to; null if clanless */
 	user_clan_id: number | null;
-	/** Cooldown-until date string; null if no cooldown */
+	/** Switch-cooldown expiry as ISO 8601 UTC string ("YYYY-MM-DDTHH:MM:SS"
+	 * with no timezone suffix; interpret as UTC). `null` when no cooldown.
+	 * User-level: while set, the user cannot join any clan. */
 	cooldown_until: string | null;
 	/** Epoch ms when the current user joined their clan; null if clanless */
 	join_date: number | null;
@@ -583,35 +591,71 @@ export interface TClans {
 
 /**
  * TClanInfo describes the detailed info of a single clan including its members.
+ * Returned by `_smartico.api.getClanInfo(clanId)`.
  */
 export interface TClanInfo {
+	/** Clan ID. */
 	clan_id: number;
+	/** Translated clan metadata (name, description, image URL). */
 	public_meta: { name: string; description: string; image_url: string };
+	/** Current number of members in clan. */
 	member_count: number;
+	/** Max number of members allowed in clan. */
 	capacity_limit: number;
+	/** Currency type for `entry_fee_amount`. `0` = points, `1` = gems,
+	 * `2` = diamonds, `3` = free. */
 	entry_fee_currency_type_id: number;
+	/** Entry fee amount in the currency indicated by `entry_fee_currency_type_id`. */
 	entry_fee_amount: number;
+	/** Global rank among all active clans in the label, by `rating_score` DESC.
+	 * `1` = highest-rated. */
 	rating_position: number;
+	/** Clan rating score (higher is better). */
 	rating_score: number;
+	/** User-level switch-cooldown expiry as ISO 8601 UTC string
+	 * ("YYYY-MM-DDTHH:MM:SS" with no timezone suffix). `null` when no
+	 * cooldown. Same semantic as `TClans.cooldown_until` but always fresh
+	 * (the list version may be up to 30 s stale). */
 	cooldown_until: string | null;
+	/** Members of this clan, server-ordered by `contribution_score` DESC
+	 * (i.e. `position` ASC). */
 	members: {
+		/** Member's internal user ID. */
 		user_id: number;
+		/** Member's display username. */
 		public_username: string;
+		/** Avatar identifier; resolve via `avatar_url` below or rebuild
+		 * from `avatar_id` + brand avatar domain. */
 		avatar_id: string;
+		/** Numeric avatar ID (alternative identifier). */
 		avatar_real_id: number;
+		/** Pre-resolved CDN URL for the avatar. */
 		avatar_url?: string;
+		/** Member's rank within this clan; `1` = top contributor. */
 		position: number;
+		/** Member's contribution to the clan rating score. */
 		contribution_score: number;
+		/** `true` when this row is the current authenticated user. */
 		is_me?: boolean;
+		/** External user identifier (operator-provided alias);
+		 * preferred over `public_username` on some surfaces. */
 		clean_ext_user_id?: string;
 	}[];
 }
 
 /**
- * TClanJoinResult describes the result of a join clan request.
+ * TClanJoinResult describes the result of a join-clan request.
+ * Note: this type uses `errCode` / `errMsg` (camelCase) — different
+ * from most other SDK result types in this library which use
+ * `err_code` / `err_message` (snake_case).
  */
 export interface TClanJoinResult {
+	/** Error code. `0` = success. Typed values are members of
+	 * {@link JoinClanErrorCode}. See `joinClan` TSDoc for the full
+	 * table and per-code UI guidance. */
 	errCode: number;
+	/** Optional server-side error message. Present only on non-zero
+	 * `errCode`; may be empty even then. */
 	errMsg: string;
 }
 
@@ -668,7 +712,9 @@ export interface TStoreItem {
 	can_buy: boolean;
 	/** The list of IDs of the categories where the store item is assigned, information about categories can be retrieved with getStoreCategories method */
 	category_ids: number[];
-	/** Number of items in the pool avaliable for the purchase.*/
+	/** Items remaining in the pool available for purchase. `null` = unlimited
+	 * supply. Positive integer = remaining stock. `0` = sold out but still
+	 * returned (operator may instead hide pool-empty items entirely). */
 	pool?: number;
 	/** The custom data of the store item defined by operator. Can be a JSON object, string or number */
 	custom_data: any;
@@ -688,6 +734,8 @@ export interface TStoreItem {
 	purchase_type: 'points' | 'gems' | 'diamonds';
 	/** The date when the store item will be available till */
 	active_till_date?: number;
+	/** Should countdown timer be shown when `active_till_date` is present */
+	show_timer?: boolean;
 	/** The discounted price of the store item */
 	discounted_price?: number;
 	/** The ribbon of the discounted price. */
@@ -705,14 +753,24 @@ export interface TStoreItem {
 }
 
 /**
- * TAchCategory describes the badge category item. Each badge item can be assigned to 1 or more categories
+ * TAchCategory describes a mission/badge category. Categories are
+ * operator-defined groupings, configured per-label by the brand operator,
+ * shared across BOTH missions and badges — the same list is returned for
+ * both entity types. A mission or badge can belong to **zero or more**
+ * categories (many-to-many) via its `category_ids: number[]` field on
+ * `TMissionOrBadge`.
+ *
+ * Returned by `_smartico.api.getAchCategories()`. See that method's TSDoc
+ * for translation, refresh, and rendering details.
  */
 export interface TAchCategory {
-	/**ID of the badge category */
+	/** Stable numeric ID of the category. Used as the key when joining to
+	 * `TMissionOrBadge.category_ids: number[]`. */
 	id: number;
-	/**Name of the badge category */
+	/** Display name of the category, pre-translated server-side. Never null. */
 	name: string;
-	/**Order of the badge category among other categories. Default value is 1 */
+	/** Relative display position (lower = appears first). Default 1 when the
+	 * operator did not configure an explicit order. */
 	order: number;
 }
 
@@ -768,8 +826,8 @@ export interface TMissionOrBadge {
 	/** The text of the CTA button, e.g. 'Make a deposit' */
 	cta_text: string;
 	/**
-	 * The ID of the custom section where the mission or badge is assigned
-	 * The list of custom sections can be retrieved using _smartico.api.getCustomSections() method (TODO-API)
+	 * The ID of the custom section where the mission or badge is assigned.
+	 * Resolve to section metadata via `_smartico.api.getCustomSections()`.
 	 */
 	custom_section_id: number;
 	/** The indicator if the mission or badge is visible only in the custom section and should be hidden from the main overview of missions/badges */
@@ -796,7 +854,8 @@ export interface TMissionOrBadge {
 	/** The ribbon of the mission/badge item. Can be 'sale', 'hot', 'new', 'vip' or URL to the image in case of custom ribbon, 250x300px */
 	ribbon?: TRibbon;
 
-	/** ID of the completion fact from ach_completed or ach_completed_recurring tables */
+	/** Stable identifier of this specific mission completion. Undefined for
+	 * badges and for missions that have not yet completed. */
 	ach_completed_id?: number;
 
 	/** Flag from achievement if the mission prize will be given only after user claims it */
@@ -901,248 +960,345 @@ export interface TMissionOrBadgeTask {
 }
 
 /**
- * TMissionOptInResult describes the response of call to _smartico.api.requestMissionOptIn(mission_id) method
+ * Response of `_smartico.api.requestMissionOptIn(mission_id)`.
+ *
+ * See `requestMissionOptIn` TSDoc for the full table of `err_code` values
+ * and recommended UI handling.
  */
 export interface TMissionOptInResult {
-	/** Error code that represents outcome of the opt-in request. Successful opt-in in case err_code is 0 */
+	/** Error code. `0` = success. See `requestMissionOptIn` TSDoc for the full table. */
 	err_code: number;
-	/** Optional error message */
+	/** Optional error message; populated on non-zero `err_code`. */
 	err_message: string;
 }
 
 /**
- * TMissionClaimRewardResult describes the response of call to _smartico.api.requestMissionClaimReward(mission_id, ach_completed_id) method
+ * Response of `_smartico.api.requestMissionClaimReward(mission_id, ach_completed_id)`.
+ *
+ * See `requestMissionClaimReward` TSDoc for the full table of `err_code`
+ * values, preconditions, side effects, and recommended UI handling.
  */
 export interface TMissionClaimRewardResult {
-	/** Error code that represents outcome of the claim request. Successful claim reward in case err_code is 0 */
+	/** Error code. `0` = success (rewards credited). See `requestMissionClaimReward` TSDoc for the full table. */
 	err_code: number;
-	/** Optional error message */
+	/** Optional error message; populated on non-zero `err_code`. */
 	err_message: string;
 }
 
+/**
+ * Result of `_smartico.api.registerInTournament(tournament_id)`.
+ */
 export interface TTournamentRegistrationResult {
-	/** Error code that represents outcome of the tournament registration request. Successful registration in case err_code is 0 */
+	/** Error code. `0` = success. See `registerInTournament` TSDoc for the full table. */
 	err_code: TournamentRegistrationError;
-	/** Optional error message */
+	/** Optional error message; populated on non-zero `err_code`. */
 	err_message: string;
 }
 
+/**
+ * Result of `_smartico.api.buyStoreItem(store_item_id)`.
+ */
 export interface TBuyStoreItemResult {
-	/** Error code representing the result of the purchase of the shop item. Successful purchase if err_code is 0 
-	 *
-	 * Example for error handling:
-	 * ```javascript
-	 * SmarticoAPI.buyStoreItem(item_id).then(res => {
-	 *   if (res.err_code !== 0) {
-	 *     // YOUR LOGIC HERE, you can use res.err_message, but it's optional and not always present
-	 *   }
-	 * });
-	 * ```
-	*/
+	/** Error code. `0` = success. See `buyStoreItem` TSDoc for the full table. */
 	err_code: BuyStoreItemErrorCode;
-	/** Optional error message */
+	/** Optional error message; populated on non-zero `err_code`. */
 	err_message: string;
 }
 
+/**
+ * Result of `getTranslations(lang_code)`.
+ */
 export interface TGetTranslations {
+	/** Flat dictionary of operator-defined translation key → translated string. */
 	translations: { [key: string]: string };
 }
 
+/**
+ * TInboxMessage is the lightweight envelope returned by
+ * `_smartico.api.getInboxMessages()`. Fetch the rich body (title,
+ * preview, icon, html_body, buttons) separately via
+ * `_smartico.api.getInboxMessageBody(message_guid)`.
+ */
 export interface TInboxMessage {
-	/** Uniq identifier of the message. It is needed to request the message body, mark the message as read/deleted/favorite. */
+	/** Unique identifier of the message. Pass to `getInboxMessageBody`
+	 * and the mark / favorite / delete mutations. */
 	message_guid: string;
-	/** Date when the message was sent */
+	/** Date when the message was sent (server timestamp). */
 	sent_date: string;
-	/** Indicator if a message is read */
+	/** `true` when the message has been marked read. */
 	read: boolean;
-	/** Indicator if a message is added to favorites */
+	/** `true` when the message has been starred (favorited). */
 	favorite: boolean;
-	/** Category id per inbox message, can be part of System inboxes, Personal inboxes or General inbox messages */
+	/** Operator-assigned category ({@link InboxCategories}). */
 	category_id?: InboxCategories;
-	/** The epoch timestamp, with milliseconds, when the message is going to be expired  */
+	/** Expiry timestamp as Unix-ms epoch. Server filters out expired
+	 * messages from list responses — consumers rarely see this set
+	 * unless the expiry is upcoming. */
 	expire_on_dt?: number;
 }
 
+/**
+ * TInboxMessageBody is the rich body of one inbox message.
+ * Returned by `_smartico.api.getInboxMessageBody(message_guid)`.
+ * Fetched from a CDN (not over WebSocket).
+ */
 export interface TInboxMessageBody {
-	/** Message title */
+	/** Display title. */
 	title: string;
-	/** Short preview body of the message */
+	/** Short preview text (typically rendered alongside the title in list items). */
 	preview_body: string;
-	/** Message icon, 128x128px */
+	/** Message icon URL (128×128 px recommended). */
 	icon: string;
-	/** The action that should be performed when user clicks on the message.
-	 * Can be URL or deep link, e.g. 'dp:deposit'. The most safe to execute CTA is to pass it to _smartico.dp(cta_action);
-	 * The 'dp' function will handle the CTA and will execute it in the most safe way.
-	 * If the message has a rich html body - the action will always be 'dp:inbox' which will open the inbox widget when triggered. 
-	*/
+	/** Click-action — either a deep-link (e.g. `'dp:deposit'`) or a
+	 * plain URL. The literal `'dp:inbox'` indicates the message has a
+	 * rich `html_body`; for any other value `html_body` and `buttons`
+	 * are absent. Pass to `_smartico.dp(action)` for safe execution. */
 	action: string;
-	/** Rich HTML body of the message. */
+	/** Rich HTML body. Populated only when `action === 'dp:inbox'`. */
 	html_body?: string;
-	/** Optional additional buttons to show in the message, available only if message has rich HTML body. Max count - 2. */
+	/** Up to 2 additional action buttons. Populated only when
+	 * `action === 'dp:inbox'`. */
 	buttons?: {
-		/** The action that should be performed when user clicks on the button. The logic is the same as for message actions */
+		/** Button click-action (deep-link or URL). */
 		action: string;
-		/** Button text */
+		/** Button label. */
 		text: string;
 	}[];
-	/** The custom data of the inbox message defined by operator. Can be a JSON object, string or number */
+	/** Operator-defined custom data. The SDK auto-parses JSON-looking
+	 * strings, so at runtime this is `any` despite the `string` type. */
 	custom_data?: string;
 }
 
+/**
+ * InboxMarkMessageAction is the response of the five inbox mutation
+ * methods (`markInboxMessageAsRead`, `markAllInboxMessagesAsRead`,
+ * `markUnmarkInboxMessageAsFavorite`, `deleteInboxMessage`,
+ * `deleteAllInboxMessages`).
+ */
 export interface InboxMarkMessageAction {
-	/** An error code representing the result of marking a message as deleted, favorite or read. Successful marking action if err_code is 0 */
+	/** Error code. `0` = success. See the calling method's TSDoc for
+	 * the full error semantics (server returns generic codes; the
+	 * five inbox mutations share the same shape). */
 	err_code: number;
-	/** Optional error message */
+	/** Optional server-side error message. Present only on non-zero
+	 * `err_code`; may be empty even then. */
 	err_message: string;
 }
 
+/**
+ * LeaderBoardDetailsT describes one period's leaderboard.
+ * Returned by `_smartico.api.getLeaderBoard(periodType, getPreviousPeriod?)`.
+ * May be `undefined` at runtime when no board is configured for the requested period.
+ */
 export interface LeaderBoardDetailsT {
-	/** ID of the leaderboard */
+	/** Stable ID of the leaderboard. */
 	board_id: number;
-	/** Name of the leaderboard */
+	/** Operator-defined display name. */
 	name: string;
-	/** Description of the leaderboard */
+	/** Operator-defined description (HTML allowed). */
 	description: string;
-	/** Rules of the leaderboard */
+	/** Operator-defined rules / terms (HTML allowed). */
 	rules: string;
-	/** Leaderboard period type ID */
+	/** Period type this board is bound to ({@link LeaderBoardPeriodType}). */
 	period_type_id: LeaderBoardPeriodType;
-	/** Leaderboard points rewards */
+	/** Per-place prize table; the array length is the number of paid places. */
 	rewards: LeaderBoardsRewardsT[];
-	/** Leaderboard users */
+	/** Top-20 ranked entries (server-capped), sorted by `position` ASC. */
 	users: LeaderBoardUserT[];
-	/** Info about current user in leaderboard */
+	/** Current user's own entry. `undefined` for visitor sessions.
+	 * For authenticated users, `position === -1` means the user is
+	 * unranked / outside the ranked window. */
 	me?: LeaderBoardUserT;
 }
 
+/**
+ * LeaderBoardsRewardsT describes one place's prize on a leaderboard.
+ * Leaderboard prizes are always gamification points (never gems / diamonds / items).
+ */
 export interface LeaderBoardsRewardsT {
+	/** Place number (1-based). */
 	place: number;
+	/** Gamification points awarded to the user occupying this place at period finalization. */
 	points: number;
 }
 
+/**
+ * LeaderBoardUserT describes one participant row on a leaderboard.
+ */
 export interface LeaderBoardUserT {
-	/** The username of the participant */
+	/** Display username (operator-defined alias). */
 	public_username: string;
-	/** The URL to the avatar of the participant */
+	/** Resolved CDN URL for the participant's avatar. */
 	avatar_url: string;
-	/** The position of the participant in the leaderboard */
+	/** Rank in the leaderboard (DENSE_RANK over all participants).
+	 * `-1` on the `me` entry signals "unranked / outside the window". */
 	position: number;
-	/** The points of the participant in the leaderboard */
+	/** Participant's points for this period. */
 	points: number;
-	/** The indicator if the participant is current user */
+	/** `true` when this row is the current authenticated user. */
 	is_me: boolean;
 }
 
+/**
+ * UserLevelExtraCountersT exposes the user's current values for the two
+ * label-defined sliding-window level counters. Returned by
+ * `_smartico.api.getUserLevelExtraCounters()`. Both fields are
+ * `undefined` on points-only labels.
+ */
 export interface UserLevelExtraCountersT {
-	/** The counter of 1st metric used to reach the level. */
+	/** Current value of the user's first level counter. Operator-defined
+	 * semantics per label. `undefined` on points-only labels. */
 	level_counter_1?: number;
-	/** The counter of 2nd metric used to reach the level. */
+	/** Current value of the user's second level counter. Operator-defined
+	 * semantics per label. `undefined` on points-only labels. */
 	level_counter_2?: number;
 }
 
+/**
+ * TSegmentCheckResult describes one segment-membership outcome.
+ * Returned by `_smartico.api.checkSegmentListMatch()` (and used
+ * internally by `checkSegmentMatch()`).
+ */
 export interface TSegmentCheckResult {
+	/** The segment ID this result refers to (label-scoped). */
 	segment_id: number;
+	/** `true` if the user currently matches this segment. `false` also
+	 * covers the case where the segment doesn't exist for the label —
+	 * the two are not distinguishable. */
 	is_matching: boolean;
 }
 
+/**
+ * One operator-configured navigation entry. Returned by `getCustomSections()`.
+ * `section_type_id` is the dispatch key — it determines which page component the
+ * consumer mounts when the user opens this section.
+ */
 export interface TUICustomSection {
-	/** The ID of the custom section */
+	/** Stable numeric ID of the section. */
 	id: number;
-	/** The body of the custom section */
+	/** Raw HTML body for `HTML_PAGE` sections; Liquid template body for `LEVELS` (Liquid) sections. */
 	body?: string;
-	/** The image of the custom section, 64x64px */
+	/** CDN URL of the section's nav icon, 64x64 px square. */
 	menu_img?: string;
-	/** The name of the custom section */
+	/** Display name shown next to the nav icon. Pre-translated server-side. */
 	menu_name?: string;
-	/** Custom images for custom section */
+	/** JSON-serialized list of skin image overrides for themed sections (e.g. `MISSION_CUSTOM_LAYOUT`). */
 	custom_skin_images?: string;
-	/** The particular type of custom section, can be Missions, Tournaments, Lootbox and etc */
+	/** Dispatch key — see {@link AchCustomSectionType}. */
 	section_type_id?: AchCustomSectionType;
-	/** Theme of the custom section */
+	/** Themed-layout name for `MISSION_CUSTOM_LAYOUT` sections; see {@link AchCustomLayoutTheme}. */
 	theme?: AchCustomLayoutTheme;
-	/** Custom css for the custom section */
+	/** Custom CSS for themed layouts. */
 	generic_custom_css?: string;
-	/** Tabs that can be shown in custom section, e.g Overview, No Overview, All tabs */
+	/** Which tabs to render for `MISSIONS_CATEGORY` sections; see {@link AchMissionsTabsOptions}. */
 	mission_tabs_options?: AchMissionsTabsOptions;
-	/** Filter that allow to show missions by criteria */
+	/** Mission-filter rule for the Overview tab; see {@link AchOverviewMissionsFilter}. */
 	overview_missions_filter?: AchOverviewMissionsFilter;
-	/** Quantity of missions to be shown in overview */
+	/** Maximum number of missions shown in the Overview tab. */
 	overview_missions_count?: number;
-	/** URL or DP to be used for custom section */
+	/** Click target for `REDIRECT_LINK` sections — either a Smartico DP string (`dp:…`) or an external URL. */
 	url_or_dp?: string;
-	/** Data to be used for Liquid templates */
+	/** Data-context selectors for Liquid templates; see {@link LiquidEntityData}. */
 	liquid_entity_data?: LiquidEntityData[];
-	/** Tournament ID to be used for Liquid templates */
+	/** Tournament ID for a single-tournament Liquid template (`LiquidEntityData.Tournament`). */
 	ach_tournament_id?: number;
-	/** Indicates if the data should be shown as raw data (for Liquid templates) */
+	/** Operator debug flag — when `true`, Liquid renders raw context data instead of the templated HTML. */
 	show_raw_data?: boolean;
-	/** Liquid template id to be used for Liquid templates */
+	/** Liquid template ID resolved server-side; the rendered body is delivered in `body`. */
 	liquid_template?: number;
-	/** List of IDs of the categories where the badge item is assigned, information about categories can be retrieved with getAchCategories method */
+	/** Category IDs the section filters badges by — correlate with `getAchCategories()`. */
 	ach_category_ids?: number[];
-	/** List of IDs of the categories where the store item is assigned, information about categories can be retrieved with getShopCategories method */
+	/** Category IDs the section filters store items by — correlate with `getStoreCategories()`. */
 	shop_category_ids?: number[];
-	/** ID of the raffle to be used for Liquid templates */
+	/** Raffle ID for `RAFFLE` sections (and `LiquidEntityData.SingleRaffle` Liquid templates). */
 	raffle_id?: number;
 }
 
+/**
+ * TBonus describes one bonus awarded to the user.
+ * Returned by `_smartico.api.getBonuses()`.
+ */
 export interface TBonus {
-	/** ID of the bonus */
+	/** Stable ID of the bonus. */
 	bonus_id: number;
-	/** Can the bonus be redeemed (if bonus is redeemable the user needs to claim it) */
+	/** `true` when the bonus is in a player-claim-required state.
+	 * Gate the Claim button on this; see `claimBonus` TSDoc. */
 	is_redeemable?: boolean;
-	/** Date of creation */
+	/** Bonus creation timestamp as ISO 8601 UTC string
+	 * ("YYYY-MM-DDTHH:MM:SS", no timezone suffix). */
 	create_date?: string;
-	/** Date of redemption */
+	/** Bonus redemption timestamp as ISO 8601 UTC string. Absent until
+	 * the bonus reaches `BonusStatus.REDEEMED`. */
 	redeem_date?: string;
-	/** ID of template used */
+	/** ID of the bonus template used to issue this bonus. */
 	label_bonus_template_id?: number;
-	/** ID of the bonus status */
+	/** Lifecycle status; see {@link BonusStatus}. */
 	bonus_status_id?: BonusStatus;
-	/** Additional information about the bonus(edscription, image,name, acknowledge) */
+	/** Template-level display metadata (operator-configured, identical
+	 * across all bonuses from the same template). */
 	label_bonus_template_meta_map?: BonusTemplateMetaMap;
-	/** Additional information presented to the player when the bonus is redeemed */
+	/** Instance-level display metadata (per-issuance; carries the
+	 * dynamic amount computed at award time). */
 	bonus_meta_map?: BonusMetaMap;
 }
 
+/**
+ * BonusStatus describes the lifecycle stage of a bonus on `TBonus.bonus_status_id`.
+ * Operator widget configuration typically filters out internal statuses
+ * (`New`, `COUPON_ISSUE_FAILED`, `EXPIRED`); consumers usually see
+ * `COUPON_ISSUED`, `REDEEMED`, and `REDEEM_FAILED`.
+ */
 export enum BonusStatus {
-	/** The bonus is newly created (shouldn't be shown to the client) */
+	/** Newly created, not yet processed (internal). */
 	New = 1,
-	/** The bonus is issued and available for redemption but has not been redeemed yet */
+	/** Issued and awaiting player claim. */
 	COUPON_ISSUED = 2,
-	/** The bonus has been successfully redeemed */
+	/** Successfully redeemed. */
 	REDEEMED = 3,
-	/** The bonus is still valid, but a previous redemption attempt failed */
+	/** Previous redemption attempt failed; still valid and re-claimable. */
 	REDEEM_FAILED = 4,
-	/** Failed to issue the bonus (shouldn't be shown to the client) */
+	/** Coupon issuance failed (internal). */
 	COUPON_ISSUE_FAILED = 5,
-	/** The bonus was issued but has expired and can no longer be redeemed (shouldn't be shown to the client) */
+	/** Issued but expired before redemption (internal). */
 	EXPIRED = 6,
 }
+/**
+ * Template-level bonus display metadata (operator-configured at the
+ * bonus template; identical for every bonus issued from the same template).
+ */
 export interface BonusTemplateMetaMap {
-	/** Description of the bonus template*/
+	/** Operator-set description / display text. May include HTML. */
 	description: string;
-	/** Acknowledge message setup in the bonus template*/
+	/** Operator-set additional message shown to the player at claim
+	 * time (e.g. wagering terms). May include deep-links. */
 	acknowledge: string;
-	/** Image URL of the bonus template, 1:1 aspect ratio */
+	/** Bonus icon URL (1:1 aspect ratio recommended). */
 	image_url: string;
-	/** Redirect URL of the bonus template*/
+	/** Optional redirect — external HTTP URL (opens in new tab) or
+	 * internal deep-link (handled by the SDK's deep-link router). */
 	redirect_url?: string;
 }
+/**
+ * Instance-level bonus display metadata (set per-issuance, may carry
+ * a dynamically-computed amount).
+ */
 export interface BonusMetaMap {
-	/** Label and description of the bonus sent to the player*/
+	/** Display-ready amount string (e.g. "€50", "100 free spins"). */
 	uiAmount?: string;
 }
 
 /**
- * TClaimBonusResult describes the response of call to _smartico.api.claimBonus(bonus_id) method
+ * TClaimBonusResult describes the response of `_smartico.api.claimBonus(bonus_id)`.
+ */
+/**
+ * Result of `_smartico.api.claimBonus(bonus_id)`.
  */
 export interface TClaimBonusResult {
-	/** Error code that represents outcome of the game play attempt. Game succeed to be played in case err_code is 0 */
-	err_code: SAWSpinErrorCode;
-	/** Optional error message */
+	/** Error code. `0` = success. See `claimBonus` TSDoc for the full table. */
+	err_code: number;
+	/** Optional error message; populated on non-zero `err_code`. */
 	err_message: string;
-	/** If the bonus was claimed successfully, then success is true */
+	/** Unreliable on the wire — prefer `err_code === 0` as the success check. */
 	success?: boolean;
 }
 
@@ -1518,10 +1674,23 @@ export interface TRaffleDrawRun {
 
 }
 
+/**
+ * TransformedRaffleClaimPrizeResponse describes the response of
+ * `_smartico.api.claimRafflePrize({won_id})`.
+ *
+ * Note: this type uses `errorCode` / `errorMessage` (camelCase
+ * full-word) — different from most other SDK wrapper-result types in
+ * this library which use `err_code` / `err_message` (snake_case).
+ */
+/**
+ * Result of `_smartico.api.claimRafflePrize({raffle_id, draw_id, raffle_run_id})`.
+ * Uses camelCase `errorCode` / `errorMessage` — distinct from most other SDK
+ * result wrappers which use snake_case `err_code` / `err_message`.
+ */
 export interface TransformedRaffleClaimPrizeResponse {
-	/** Error code, 0 means no error */
+	/** Error code. `0` = success. See `claimRafflePrize` TSDoc for the full table. */
 	errorCode: number
-	/** Error message, will be exposed only if ErrorCode is not 0 */
+	/** Optional error message; populated on non-zero `errorCode`. */
 	errorMessage?: string
 }
 /**
@@ -1548,10 +1717,13 @@ export interface TActivityLog {
 }
 
 
+/**
+ * Result of `_smartico.api.requestRaffleOptin({raffle_id, draw_id, raffle_run_id})`.
+ */
 export interface TRaffleOptinResponse {
-	/** Error code that represents outcome of the opt-in attempt. Opt-in succeed in case err_code is 0 */
+	/** Error code. `0` = success. See `requestRaffleOptin` TSDoc for the full table. */
 	err_code: number;
-	/** Optional error message */
+	/** Optional error message; populated on non-zero `err_code`. */
 	err_message?: string;
 }
 
@@ -2024,75 +2196,72 @@ export interface GamePickRoundRequestParams extends GamePickRequestParams {
 }
 
 /**
- * TAvatarDefinition describes a single avatar available in the avatar catalog.
+ * One avatar in the user's catalog. Returned by `getAvatarsList()`.
  * Fields from the raw `public_meta` object are flattened to the top level.
  */
 export interface TAvatarDefinition {
-	/** Unique identifier of the avatar */
+	/** Stable numeric identifier of the avatar. Primary key passed to `setAvatar()`. */
 	avatar_real_id: number;
-	/** Whether this avatar is the default one */
+	/** True when this is the system default avatar for the label. */
 	is_default: boolean;
-	/** If true, avatar is hidden until user achieves/unlocks it */
+	/** When true and `is_given === false`, the avatar should be hidden from the user (surprise unlock). */
 	hide_until_achieved: boolean;
-	/** Display priority — lower value means higher position in the grid */
+	/** Display position; lower = earlier in the grid. */
 	priority: number;
-	/** Optional description of the avatar (from public_meta) */
+	/** Optional description shown alongside the avatar in detail views. */
 	description?: string;
-	/** Raw image path/URL of the avatar as returned by the server (from public_meta) */
+	/** Raw image path as returned by the server (relative or absolute). */
 	url: string;
-	/** Full CDN URL of the avatar image, built from avatar_domain + url */
+	/** Absolute CDN URL of the avatar image; built from the configured avatar domain + `url`. */
 	avatar_url: string;
-	/**
-	 * Source type of the avatar.
-	 * 0 = free (always available to all users), other values = earned/purchased
-	 */
+	/** Source type. `0` = free / always available; non-zero = earned or purchased. */
 	avatar_source_type_id: number;
-	/** ISO date string from which the avatar becomes available */
+	/** ISO date string from which the avatar becomes available; undefined when no start window. */
 	active_from_date?: string;
-	/** ISO date string until which the avatar is available */
+	/** ISO date string until which the avatar is available; undefined when no end window. */
 	active_till_date?: string;
-	/** Whether the avatar has been granted/given to the current user */
+	/** True when the user owns / has unlocked this avatar. */
 	is_given: boolean;
-	/** Whether this avatar is currently in use by the user */
+	/** True when this avatar is the user's currently active profile avatar. */
 	is_in_use?: boolean;
 }
 
 /**
- * TAvatarCustomized describes an AI-customized version of a base avatar
+ * One AI-generated variant of a base avatar. Returned by `getAvatarsCustomized()`.
  */
 export interface TAvatarCustomized {
-	/** The avatar_real_id of the base avatar this customization was generated from */
+	/** `avatar_real_id` of the base avatar this variant was generated from. */
 	avatar_real_id: number;
-	/** Full CDN URL of the AI-generated customized avatar image */
+	/** Absolute CDN URL of the AI-generated image. Can be passed as `avatar_url` to `setAvatar()`. */
 	url: string;
-	/** ISO date string when the customization was created */
+	/** ISO date string of when the variant was generated. */
 	dt_created: string;
 }
 
 /**
- * TAvatarPrompt describes an AI style prompt available for avatar customization.
+ * One AI style prompt for avatar customization. Returned by `getAvatarPrompts()`.
  * Fields from the raw `public_meta` object are flattened to the top level.
  */
 export interface TAvatarPrompt {
-	/** Unique identifier of the AI customization prompt */
+	/** Stable numeric identifier of the prompt. */
 	prompt_id: number;
-	/** Display name of the prompt style, e.g. "Cartoon", "Watercolor" (from public_meta) */
+	/** Display name of the style, e.g. "Cartoon", "Watercolor". */
 	name: string;
-	/** Full CDN URL of the prompt style icon image (from public_meta) */
+	/** Absolute CDN URL of the prompt's preview icon. */
 	icon_url: string;
-	/** Currency type used to pay for this customization (0=points, 1=gems, 2=diamonds) */
+	/** Currency used to pay for the customization. `0` = points, `1` = gems, `2` = diamonds. */
 	cost_currency_type_id: number;
-	/** Cost amount in the given currency */
+	/** Cost amount in the currency named by `cost_currency_type_id`. */
 	cost_value: number;
 }
 
 /**
- * TSetAvatarResult describes the response of call to _smartico.api.setAvatar() method
+ * Result of `_smartico.api.setAvatar()`.
  */
 export interface TSetAvatarResult {
-	/** Error code that represents outcome of the set avatar request. Successful if err_code is 0 */
+	/** Error code. `0` = success. See `setAvatar` TSDoc for the full table. */
 	err_code: number;
-	/** Optional error message */
+	/** Optional error message; populated on non-zero `err_code`. */
 	err_message?: string;
 }