@smartico/public-api 0.0.380 → 0.0.382

package/docs/api/interfaces/LeaderBoardUserT.md

@@ -1,12 +1,14 @@
 # Interface: LeaderBoardUserT
 
+LeaderBoardUserT describes one participant row on a leaderboard.
+
 ## Properties
 
 ### public\_username
 
 > **public\_username**: `string`
 
-The username of the participant
+Display username (operator-defined alias).
 
 ***
 
@@ -14,7 +16,7 @@ The username of the participant
 
 > **avatar\_url**: `string`
 
-The URL to the avatar of the participant
+Resolved CDN URL for the participant's avatar.
 
 ***
 
@@ -22,7 +24,8 @@ The URL to the avatar of the participant
 
 > **position**: `number`
 
-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".
 
 ***
 
@@ -30,7 +33,7 @@ The position of the participant in the leaderboard
 
 > **points**: `number`
 
-The points of the participant in the leaderboard
+Participant's points for this period.
 
 ***
 
@@ -38,4 +41,4 @@ The points of the participant in the leaderboard
 
 > **is\_me**: `boolean`
 
-The indicator if the participant is current user
+`true` when this row is the current authenticated user.

package/docs/api/interfaces/LeaderBoardsRewardsT.md

@@ -1,13 +1,20 @@
 # Interface: LeaderBoardsRewardsT
 
+LeaderBoardsRewardsT describes one place's prize on a leaderboard.
+Leaderboard prizes are always gamification points (never gems / diamonds / items).
+
 ## Properties
 
 ### place
 
 > **place**: `number`
 
+Place number (1-based).
+
 ***
 
 ### points
 
 > **points**: `number`
+
+Gamification points awarded to the user occupying this place at period finalization.

package/docs/api/interfaces/PointsLog.md

@@ -0,0 +1,43 @@
+# Interface: PointsLog
+
+## Properties
+
+### create\_date
+
+> **create\_date**: `number`
+
+***
+
+### user\_ext\_id
+
+> **user\_ext\_id**: `string`
+
+***
+
+### crm\_brand\_id
+
+> **crm\_brand\_id**: `number`
+
+***
+
+### points\_collected
+
+> **points\_collected**: `number`
+
+***
+
+### user\_points\_ever
+
+> **user\_points\_ever**: `number`
+
+***
+
+### user\_points\_balance
+
+> **user\_points\_balance**: `number`
+
+***
+
+### source\_type\_id
+
+> **source\_type\_id**: [`PointChangeSourceType`](../enumerations/PointChangeSourceType.md)

package/docs/api/interfaces/RaffleWonPrize.md

@@ -0,0 +1,59 @@
+# Interface: RaffleWonPrize
+
+A single prize the user won within the raffle.
+
+## Properties
+
+### raf\_won\_id
+
+> **raf\_won\_id**: `number`
+
+Unique ID of the winning row (pass to `claimRafflePrize` when `requires_claim` is `true`).
+
+***
+
+### prize\_id
+
+> **prize\_id**: `number`
+
+ID of the prize definition.
+
+***
+
+### raffle\_run\_id
+
+> **raffle\_run\_id**: `number`
+
+Run-instance ID of the draw that awarded this prize.
+
+***
+
+### draw\_id
+
+> **draw\_id**: `number`
+
+Schedule ID of the draw that awarded this prize.
+
+***
+
+### public\_meta
+
+> **public\_meta**: [`RaffleWonPrizePublicMeta`](RaffleWonPrizePublicMeta.md)
+
+Presentation meta (name / image).
+
+***
+
+### requires\_claim
+
+> **requires\_claim**: `boolean`
+
+Whether this prize requires a claim action from the user.
+
+***
+
+### claimed\_date
+
+> **claimed\_date**: `number`
+
+Epoch ms when the prize was claimed; `null` when not yet claimed.

package/docs/api/interfaces/RaffleWonPrizePublicMeta.md

@@ -0,0 +1,27 @@
+# Interface: RaffleWonPrizePublicMeta
+
+Presentation meta for a won prize.
+
+## Properties
+
+### name
+
+> **name**: `string`
+
+Name of the prize, e.g. '1 $'.
+
+***
+
+### hide\_chance\_to\_win
+
+> **hide\_chance\_to\_win**: `boolean`
+
+Indicates whether the chance to win should be hidden in the UI.
+
+***
+
+### image\_url
+
+> **image\_url**: `string`
+
+URL of the image that represents the prize.

package/docs/api/interfaces/RaffleWonPrizeUser.md

@@ -0,0 +1,43 @@
+# Interface: RaffleWonPrizeUser
+
+The user the won-prizes list belongs to.
+
+## Properties
+
+### user\_id
+
+> **user\_id**: `number`
+
+Internal user ID.
+
+***
+
+### avatar\_id
+
+> **avatar\_id**: `string`
+
+Avatar image: a full URL for a system avatar, otherwise an avatar token to resolve against the widget's avatar domain.
+
+***
+
+### avatar\_real\_id
+
+> **avatar\_real\_id**: `number`
+
+Numeric ID of the user's selected avatar definition.
+
+***
+
+### public\_username?
+
+> `optional` **public\_username?**: `string`
+
+Public username; server-masked for other users (e.g. `"32:r*****"`).
+
+***
+
+### avatar\_url?
+
+> `optional` **avatar\_url?**: `string`
+
+Always `null` on the wire — use `avatar_id`.

package/docs/api/interfaces/TAchCategory.md

@@ -25,10 +25,7 @@ Stable numeric ID of the category. Used as the key when joining to
 
 > **name**: `string`
 
-Display name of the category. **Pre-translated server-side** to the authenticated
-user's stored language (or to the language passed to `_smartico.vapi(lang)` in
-visitor mode). Falls back to the EN base name when a translation is missing — never
-null. Consumers should NOT translate this further.
+Display name of the category, pre-translated server-side. Never null.
 
 ***
 
@@ -36,7 +33,5 @@ null. Consumers should NOT translate this further.
 
 > **order**: `number`
 
-Relative position among other categories (lower = appears first). The server does
-NOT pre-sort by this value — the consumer must sort:
-`categories.sort((a, b) => a.order - b.order)`. Default value is 1 when the
+Relative display position (lower = appears first). Default 1 when the
 operator did not configure an explicit order.

package/docs/api/interfaces/TAvatarCustomized.md

@@ -1,6 +1,6 @@
 # Interface: TAvatarCustomized
 
-TAvatarCustomized describes an AI-customized version of a base avatar
+One AI-generated variant of a base avatar. Returned by `getAvatarsCustomized()`.
 
 ## Properties
 
@@ -8,7 +8,7 @@ TAvatarCustomized describes an AI-customized version of a base avatar
 
 > **avatar\_real\_id**: `number`
 
-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.
 
 ***
 
@@ -16,7 +16,7 @@ The avatar_real_id of the base avatar this customization was generated from
 
 > **url**: `string`
 
-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()`.
 
 ***
 
@@ -24,4 +24,4 @@ Full CDN URL of the AI-generated customized avatar image
 
 > **dt\_created**: `string`
 
-ISO date string when the customization was created
+ISO date string of when the variant was generated.

package/docs/api/interfaces/TAvatarDefinition.md

@@ -1,6 +1,6 @@
 # Interface: TAvatarDefinition
 
-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.
 
 ## Properties
@@ -9,7 +9,7 @@ Fields from the raw `public_meta` object are flattened to the top level.
 
 > **avatar\_real\_id**: `number`
 
-Unique identifier of the avatar
+Stable numeric identifier of the avatar. Primary key passed to `setAvatar()`.
 
 ***
 
@@ -17,7 +17,7 @@ Unique identifier of the avatar
 
 > **is\_default**: `boolean`
 
-Whether this avatar is the default one
+True when this is the system default avatar for the label.
 
 ***
 
@@ -25,7 +25,7 @@ Whether this avatar is the default one
 
 > **hide\_until\_achieved**: `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).
 
 ***
 
@@ -33,7 +33,7 @@ If true, avatar is hidden until user achieves/unlocks it
 
 > **priority**: `number`
 
-Display priority — lower value means higher position in the grid
+Display position; lower = earlier in the grid.
 
 ***
 
@@ -41,7 +41,7 @@ Display priority — lower value means higher position in the grid
 
 > `optional` **description?**: `string`
 
-Optional description of the avatar (from public_meta)
+Optional description shown alongside the avatar in detail views.
 
 ***
 
@@ -49,7 +49,7 @@ Optional description of the avatar (from public_meta)
 
 > **url**: `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).
 
 ***
 
@@ -57,7 +57,7 @@ Raw image path/URL of the avatar as returned by the server (from public_meta)
 
 > **avatar\_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`.
 
 ***
 
@@ -65,8 +65,7 @@ Full CDN URL of the avatar image, built from avatar_domain + url
 
 > **avatar\_source\_type\_id**: `number`
 
-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.
 
 ***
 
@@ -74,7 +73,7 @@ Source type of the avatar.
 
 > `optional` **active\_from\_date?**: `string`
 
-ISO date string from which the avatar becomes available
+ISO date string from which the avatar becomes available; undefined when no start window.
 
 ***
 
@@ -82,7 +81,7 @@ ISO date string from which the avatar becomes available
 
 > `optional` **active\_till\_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.
 
 ***
 
@@ -90,7 +89,7 @@ ISO date string until which the avatar is available
 
 > **is\_given**: `boolean`
 
-Whether the avatar has been granted/given to the current user
+True when the user owns / has unlocked this avatar.
 
 ***
 
@@ -98,4 +97,4 @@ Whether the avatar has been granted/given to the current user
 
 > `optional` **is\_in\_use?**: `boolean`
 
-Whether this avatar is currently in use by the user
+True when this avatar is the user's currently active profile avatar.

package/docs/api/interfaces/TAvatarPrompt.md

@@ -1,6 +1,6 @@
 # Interface: TAvatarPrompt
 
-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.
 
 ## Properties
@@ -9,7 +9,7 @@ Fields from the raw `public_meta` object are flattened to the top level.
 
 > **prompt\_id**: `number`
 
-Unique identifier of the AI customization prompt
+Stable numeric identifier of the prompt.
 
 ***
 
@@ -17,7 +17,7 @@ Unique identifier of the AI customization prompt
 
 > **name**: `string`
 
-Display name of the prompt style, e.g. "Cartoon", "Watercolor" (from public_meta)
+Display name of the style, e.g. "Cartoon", "Watercolor".
 
 ***
 
@@ -25,7 +25,7 @@ Display name of the prompt style, e.g. "Cartoon", "Watercolor" (from public_meta
 
 > **icon\_url**: `string`
 
-Full CDN URL of the prompt style icon image (from public_meta)
+Absolute CDN URL of the prompt's preview icon.
 
 ***
 
@@ -33,7 +33,7 @@ Full CDN URL of the prompt style icon image (from public_meta)
 
 > **cost\_currency\_type\_id**: `number`
 
-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.
 
 ***
 
@@ -41,4 +41,4 @@ Currency type used to pay for this customization (0=points, 1=gems, 2=diamonds)
 
 > **cost\_value**: `number`
 
-Cost amount in the given currency
+Cost amount in the currency named by `cost_currency_type_id`.

package/docs/api/interfaces/TBonus.md

@@ -1,12 +1,15 @@
 # Interface: TBonus
 
+TBonus describes one bonus awarded to the user.
+Returned by `_smartico.api.getBonuses()`.
+
 ## Properties
 
 ### bonus\_id
 
 > **bonus\_id**: `number`
 
-ID of the bonus
+Stable ID of the bonus.
 
 ***
 
@@ -14,7 +17,8 @@ ID of the bonus
 
 > `optional` **is\_redeemable?**: `boolean`
 
-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.
 
 ***
 
@@ -22,7 +26,8 @@ Can the bonus be redeemed (if bonus is redeemable the user needs to claim it)
 
 > `optional` **create\_date?**: `string`
 
-Date of creation
+Bonus creation timestamp as ISO 8601 UTC string
+("YYYY-MM-DDTHH:MM:SS", no timezone suffix).
 
 ***
 
@@ -30,7 +35,8 @@ Date of creation
 
 > `optional` **redeem\_date?**: `string`
 
-Date of redemption
+Bonus redemption timestamp as ISO 8601 UTC string. Absent until
+the bonus reaches `BonusStatus.REDEEMED`.
 
 ***
 
@@ -38,7 +44,7 @@ Date of redemption
 
 > `optional` **label\_bonus\_template\_id?**: `number`
 
-ID of template used
+ID of the bonus template used to issue this bonus.
 
 ***
 
@@ -46,7 +52,7 @@ ID of template used
 
 > `optional` **bonus\_status\_id?**: [`BonusStatus`](../enumerations/BonusStatus-1.md)
 
-ID of the bonus status
+Lifecycle status; see [BonusStatus](../enumerations/BonusStatus-1.md).
 
 ***
 
@@ -54,7 +60,8 @@ ID of the bonus status
 
 > `optional` **label\_bonus\_template\_meta\_map?**: [`BonusTemplateMetaMap`](BonusTemplateMetaMap-1.md)
 
-Additional information about the bonus(edscription, image,name, acknowledge)
+Template-level display metadata (operator-configured, identical
+across all bonuses from the same template).
 
 ***
 
@@ -62,4 +69,5 @@ Additional information about the bonus(edscription, image,name, acknowledge)
 
 > `optional` **bonus\_meta\_map?**: [`BonusMetaMap`](BonusMetaMap-1.md)
 
-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).

package/docs/api/interfaces/TBuyStoreItemResult.md

@@ -1,35 +1,14 @@
 # Interface: TBuyStoreItemResult
 
+Result of `_smartico.api.buyStoreItem(store_item_id)`.
+
 ## Properties
 
 ### err\_code
 
 > **err\_code**: [`BuyStoreItemErrorCode`](../enumerations/BuyStoreItemErrorCode.md)
 
-Outcome of the store-item purchase. `0` means the purchase succeeded
-(funds debited, reward delivered server-side); any non-zero value
-signals a failure.
-
-The typed values are the named codes in the [BuyStoreItemErrorCode](../enumerations/BuyStoreItemErrorCode.md)
-enum. Always branch on known codes first and fall back to a generic
-error handler for anything else.
-
-See the `buyStoreItem` TSDoc for the full error-code table, the
-Buy-button decision matrix, and per-code UI guidance.
-
-Example for error handling:
-```ts
-const res = await window._smartico.api.buyStoreItem(item_id);
-if (res.err_code === 0) {
-  console.log('[smartico] purchase succeeded — close the detail modal, show a success toast; the SDK auto-refreshes getStoreItems and the purchased-items list');
-} else if (res.err_code === 11000 || res.err_code === 11011 || res.err_code === 11012) {
-  console.error('[smartico] insufficient balance — show insufficient-balance UI for the item.purchase_type');
-} else if (res.err_code === 11009) {
-  console.error('[smartico] sold out — show a "Sold out" message');
-} else {
-  console.error('[smartico] purchase failed — show a generic error with this message:', res.err_message);
-}
-```
+Error code. `0` = success. See `buyStoreItem` TSDoc for the full table.
 
 ***
 
@@ -37,8 +16,4 @@ if (res.err_code === 0) {
 
 > **err\_message**: `string`
 
-Optional server-side error message describing the failure. Present
-only on non-zero `err_code`, and even then can be empty. For codes
-that have operator-defined copy on the item itself (`11006` →
-`limit_message`, `11014` → `purchase_limit_message`), prefer the
-item-level copy and use `err_message` only as a fallback.
+Optional error message; populated on non-zero `err_code`.

package/docs/api/interfaces/TClaimBonusResult.md

@@ -1,14 +1,14 @@
 # Interface: TClaimBonusResult
 
-TClaimBonusResult describes the response of call to _smartico.api.claimBonus(bonus_id) method
+Result of `_smartico.api.claimBonus(bonus_id)`.
 
 ## Properties
 
 ### err\_code
 
-> **err\_code**: [`SAWSpinErrorCode`](../enumerations/SAWSpinErrorCode.md)
+> **err\_code**: `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 `claimBonus` TSDoc for the full table.
 
 ***
 
@@ -16,7 +16,7 @@ Error code that represents outcome of the game play attempt. Game succeed to be
 
 > **err\_message**: `string`
 
-Optional error message
+Optional error message; populated on non-zero `err_code`.
 
 ***
 
@@ -24,4 +24,4 @@ Optional error message
 
 > `optional` **success?**: `boolean`
 
-If the bonus was claimed successfully, then success is true
+Unreliable on the wire — prefer `err_code === 0` as the success check.

package/docs/api/interfaces/TClan.md

@@ -52,7 +52,8 @@ Max number of members allowed in clan
 
 > **entry\_fee\_currency\_type\_id**: `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).
 
 ***
 
@@ -60,7 +61,8 @@ ShopPurchaseType: 0=Points, 1=Gems, 2=Diamonds, 3=Free
 
 > **entry\_fee\_amount**: `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.
 
 ***
 
@@ -68,7 +70,9 @@ Numeric value for entry fee
 
 > **rating\_position**: `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).
 
 ***
 
@@ -76,4 +80,4 @@ F1 rank ASC, 1=best
 
 > **rating\_score**: `number`
 
-Clan rating score
+Clan rating score (higher is better).