@smartico/public-api 0.0.379 → 0.0.380

package/dist/WSAPI/WSAPITypes.d.ts

@@ -193,85 +193,76 @@ export interface TMiniGameTemplate {
  *  _smartico.on('props_change', () => console.log(_smartico.api.getUserProfile()) );
  */
 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;
 }
 /**
@@ -300,7 +291,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 */
@@ -535,13 +526,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;
 }
 /**
@@ -552,45 +547,83 @@ 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;
 }
 /**
  * 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;
 }
 /**
@@ -645,7 +678,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;
@@ -665,6 +700,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. */
@@ -681,14 +718,24 @@ export interface TStoreItem {
     cant_buy_message?: string;
 }
 /**
- * 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;
 }
 /**
@@ -740,8 +787,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 */
@@ -760,7 +807,8 @@ export interface TMissionOrBadge {
     position?: number;
     /** 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 */
     requires_prize_claim?: boolean;
@@ -844,43 +892,47 @@ export interface TMissionOrBadgeTask {
     execution_count_actual?: number;
 }
 /**
- * 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;
 }
 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 (registration persisted, buy-in
+     * deducted). Typed values are members of {@link TournamentRegistrationError};
+     * numeric codes `300010` (insufficient gems) and `300011` (insufficient
+     * diamonds) may also be returned and are NOT currently in the enum.
+     * See `registerInTournament` TSDoc for the full table. */
     err_code: TournamentRegistrationError;
-    /** Optional error message */
+    /** Optional error message. Present only on non-zero `err_code`;
+     * may be empty even then. */
     err_message: string;
 }
 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 (funds debited and reward delivered).
+     * Typed values are the named codes in {@link BuyStoreItemErrorCode}.
+     * See `buyStoreItem` TSDoc for the full table and per-code UI guidance. */
     err_code: BuyStoreItemErrorCode;
-    /** Optional error message */
+    /** Optional server-side error message. Present only on non-zero
+     * `err_code`; may be empty even then. */
     err_message: string;
 }
 export interface TGetTranslations {
@@ -967,10 +1019,18 @@ export interface LeaderBoardUserT {
     /** The indicator if the participant is current 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;
 }
 export interface TSegmentCheckResult {