@smartico/public-api 0.0.378 → 0.0.380

package/docs/api/classes/WSAPITournaments.md

@@ -0,0 +1,104 @@
+# Class: WSAPITournaments
+## Methods
+
+### getTournamentsList()
+
+> **getTournamentsList**(`__namedParameters?`): `Promise`\<[`TTournament`](../interfaces/TTournament.md)[]\>
+
+#### Parameters
+
+##### \_\_namedParameters?
+
+###### onUpdate?
+
+(`data`) => `void`
+
+#### Returns
+
+`Promise`\<[`TTournament`](../interfaces/TTournament.md)[]\>
+
+***
+
+### getTournamentInstanceInfo()
+
+> **getTournamentInstanceInfo**(`tournamentInstanceId`): `Promise`\<[`TTournamentDetailed`](../interfaces/TTournamentDetailed.md)\>
+
+Returns detailed information for a specific tournament instance; the response includes tournament info and the leaderboard of players
+
+**Example**:
+```
+_smartico.api.getTournamentsList().then((result) => {
+     if (result.length > 0) {
+        _smartico.api.getTournamentInstanceInfo(result[0].instance_id).then((result) => {
+            console.log(result);
+       });
+    }
+});
+```
+
+**Example in the Visitor mode**:
+```
+_smartico.vapi('EN').getTournamentsList().then((result) => {
+     if (result.length > 0) {
+        _smartico.vapi('EN').getTournamentInstanceInfo(result[0].instance_id).then((result) => {
+            console.log(result);
+       });
+    }
+});
+```
+
+#### Parameters
+
+##### tournamentInstanceId
+
+`number`
+
+#### Returns
+
+`Promise`\<[`TTournamentDetailed`](../interfaces/TTournamentDetailed.md)\>
+
+***
+
+### getClanTournamentPlayers()
+
+> **getClanTournamentPlayers**(`tournamentInstanceId`, `clanId`): `Promise`\<[`TClanTournamentPlayers`](../interfaces/TClanTournamentPlayers.md)\>
+
+Returns the players of a specific clan in a clan-based tournament.
+
+**Visitor mode: not supported**
+
+#### Parameters
+
+##### tournamentInstanceId
+
+`number`
+
+##### clanId
+
+`number`
+
+#### Returns
+
+`Promise`\<[`TClanTournamentPlayers`](../interfaces/TClanTournamentPlayers.md)\>
+
+***
+
+### registerInTournament()
+
+> **registerInTournament**(`tournamentInstanceId`): `Promise`\<[`TTournamentRegistrationResult`](../interfaces/TTournamentRegistrationResult.md)\>
+
+Requests registration for the specified tournament instance. Returns the err_code.
+
+**Visitor mode: not supported**
+
+#### Parameters
+
+##### tournamentInstanceId
+
+`number`
+
+#### Returns
+
+`Promise`\<[`TTournamentRegistrationResult`](../interfaces/TTournamentRegistrationResult.md)\>
+
+***

package/docs/api/classes/WSAPIUser.md

@@ -0,0 +1,200 @@
+# Class: WSAPIUser
+## Methods
+
+### getUserProfile()
+
+> **getUserProfile**(): [`TUserProfile`](../interfaces/TUserProfile.md)
+
+#### Returns
+
+[`TUserProfile`](../interfaces/TUserProfile.md)
+
+***
+
+### checkSegmentMatch()
+
+> **checkSegmentMatch**(`segment_id`): `Promise`\<`boolean`\>
+
+Check if user belongs to specific segments
+**Example**:
+```
+_smartico.api.checkSegmentMatch(1).then((result) => {
+  console.log(result);
+});
+```
+
+**Visitor mode: not supported**
+
+#### Parameters
+
+##### segment\_id
+
+`number`
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+***
+
+### checkSegmentListMatch()
+
+> **checkSegmentListMatch**(`segment_ids`): `Promise`\<[`TSegmentCheckResult`](../interfaces/TSegmentCheckResult.md)[]\>
+
+Check if user belongs to specific list of segments
+**Example**:
+```
+_smartico.api.checkSegmentListMatch([1, 2, 3]).then((result) => {
+   console.log(result);
+});
+```
+**Visitor mode: not supported**
+
+#### Parameters
+
+##### segment\_ids
+
+`number`[]
+
+#### Returns
+
+`Promise`\<[`TSegmentCheckResult`](../interfaces/TSegmentCheckResult.md)[]\>
+
+***
+
+### getLevels()
+
+> **getLevels**(): `Promise`\<[`TLevel`](../interfaces/TLevel.md)[]\>
+
+Returns all the levels available to the current user
+**Example**:
+```
+_smartico.api.getLevels().then((result) => {
+     console.log(result);
+});
+```
+
+**Example in the Visitor mode**:
+```
+_smartico.vapi('EN').getLevels().then((result) => {
+     console.log(result);
+});
+```
+
+#### Returns
+
+`Promise`\<[`TLevel`](../interfaces/TLevel.md)[]\>
+
+***
+
+### getCurrentLevel()
+
+> **getCurrentLevel**(): `Promise`\<[`TLevelCurrent`](../interfaces/TLevelCurrent.md)\>
+
+Returns the current level of the user with extended information including ordinal position and progress.
+
+**Example**:
+```
+_smartico.api.getCurrentLevel().then((result) => {
+     console.log(result);
+});
+```
+
+**Visitor mode: not supported**
+
+#### Returns
+
+`Promise`\<[`TLevelCurrent`](../interfaces/TLevelCurrent.md)\>
+
+***
+
+### getUserLevelExtraCounters()
+
+> **getUserLevelExtraCounters**(): `Promise`\<[`UserLevelExtraCountersT`](../interfaces/UserLevelExtraCountersT.md)\>
+
+Returns the extra counters for the current user level.
+These are counters that are configured for each Smartico client separately by request.
+For example 1st counter could be total wagering amount, 2nd counter could be total deposit amount, etc.
+
+**Example**:
+```
+_smartico.api.getUserLevelExtraCounters().then((result) => {
+     console.log(result);
+});
+```
+
+**Visitor mode: not supported**
+
+#### Returns
+
+`Promise`\<[`UserLevelExtraCountersT`](../interfaces/UserLevelExtraCountersT.md)\>
+
+***
+
+### getActivityLog()
+
+> **getActivityLog**(`params`): `Promise`\<[`TActivityLog`](../interfaces/TActivityLog.md)[]\>
+
+Returns the activity log for a user within a specified time range.
+The response includes both points changes and gems/diamonds changes.
+Each log entry contains information about the change amount, balance, and source.
+The returned list is cached for 30 seconds.
+You can pass the onUpdate callback as a parameter, it will be called every time the activity log is updated and will provide the updated list of activity logs for the last 10 minutes.
+
+**Example**:
+```
+const startTime = Math.floor(Date.now() / 1000) - 86400 * 30; // 30 days ago
+const endTime = Math.floor(Date.now() / 1000); // now
+
+_smartico.api.getActivityLog({
+     startTimeSeconds: startTime,
+     endTimeSeconds: endTime,
+     from: 0,
+     to: 50,
+     onUpdate: (data) => console.log('Updated:', data)
+}).then((result) => {
+     console.log(result);
+});
+```
+
+**Visitor mode: not supported**
+
+#### Parameters
+
+##### params
+
+Activity log parameters
+
+###### startTimeSeconds
+
+`number`
+
+Start time in seconds (epoch timestamp)
+
+###### endTimeSeconds
+
+`number`
+
+End time in seconds (epoch timestamp)
+
+###### from
+
+`number`
+
+Start index of records to return
+
+###### to
+
+`number`
+
+End index of records to return
+
+###### onUpdate?
+
+(`data`) => `void`
+
+Optional callback function that will be called when the activity log is updated
+
+#### Returns
+
+`Promise`\<[`TActivityLog`](../interfaces/TActivityLog.md)[]\>

package/docs/api/enumerations/AchievementClaimPeriodTypeId.md

@@ -0,0 +1,13 @@
+# Enumeration: AchievementClaimPeriodTypeId
+
+## Enumeration Members
+
+### RelativePeriod
+
+> **RelativePeriod**: `0`
+
+***
+
+### ExactPeriod
+
+> **ExactPeriod**: `1`

package/docs/api/enumerations/BuyStoreItemErrorCode.md

@@ -2,6 +2,22 @@
 
 ## Enumeration Members
 
+### SHOP\_FAILED\_GENERIC
+
+> **SHOP\_FAILED\_GENERIC**: `1`
+
+Generic server error / control-group rejection
+
+***
+
+### SHOP\_WRONG\_LABEL\_PRECHECK
+
+> **SHOP\_WRONG\_LABEL\_PRECHECK**: `106`
+
+Label mismatch detected before purchase transaction
+
+***
+
 ### SHOP\_NO\_BALANCE
 
 > **SHOP\_NO\_BALANCE**: `11000`
@@ -58,6 +74,14 @@ Failed to buy item because of limit of max items is reached
 
 ***
 
+### SHOP\_FAILED\_BONUS\_REDEMPTION
+
+> **SHOP\_FAILED\_BONUS\_REDEMPTION**: `11007`
+
+Bonus was issued but a follow-up redemption step failed
+
+***
+
 ### SHOP\_FAILED\_POOL\_EMPTY
 
 > **SHOP\_FAILED\_POOL\_EMPTY**: `11009`
@@ -87,3 +111,11 @@ User doesn't have enough diamonds on balance
 > **SHOP\_FAILED\_PURCHASE\_LIMITATION**: `11014`
 
 Failed to buy item because of purchase limitation
+
+***
+
+### SHOP\_UNEXPECTED\_EXCEPTION
+
+> **SHOP\_UNEXPECTED\_EXCEPTION**: `9999`
+
+Uncaught server exception

package/docs/api/interfaces/ClanPrizePublicMeta.md

@@ -0,0 +1,41 @@
+# Interface: ClanPrizePublicMeta
+
+## Extends
+
+- [`ClanPublicMeta`](ClanPublicMeta.md)
+
+## Properties
+
+### name
+
+> **name**: `string`
+
+#### Inherited from
+
+[`ClanPublicMeta`](ClanPublicMeta.md).[`name`](ClanPublicMeta.md#name)
+
+***
+
+### description
+
+> **description**: `string`
+
+#### Inherited from
+
+[`ClanPublicMeta`](ClanPublicMeta.md).[`description`](ClanPublicMeta.md#description)
+
+***
+
+### image\_url
+
+> **image\_url**: `string`
+
+#### Inherited from
+
+[`ClanPublicMeta`](ClanPublicMeta.md).[`image_url`](ClanPublicMeta.md#image_url)
+
+***
+
+### prize\_name?
+
+> `optional` **prize\_name?**: `string`

package/docs/api/interfaces/ClanPrizeStructureEntry.md

@@ -22,6 +22,12 @@
 
 ***
 
+### prize\_pool\_currency\_code
+
+> **prize\_pool\_currency\_code**: `string`
+
+***
+
 ### activity\_type\_id
 
 > **activity\_type\_id**: `number`
@@ -36,7 +42,7 @@
 
 ### public\_meta
 
-> **public\_meta**: [`ClanPublicMeta`](ClanPublicMeta.md)
+> **public\_meta**: [`ClanPrizePublicMeta`](ClanPrizePublicMeta.md)
 
 ***
 

package/docs/api/interfaces/ClanPublicMeta.md

@@ -1,5 +1,9 @@
 # Interface: ClanPublicMeta
 
+## Extended by
+
+- [`ClanPrizePublicMeta`](ClanPrizePublicMeta.md)
+
 ## Properties
 
 ### name

package/docs/api/interfaces/SAWTemplateUI.md

@@ -563,3 +563,13 @@ controlling obstacle frequency and game speed.
 | `SAWGameDifficultyType.EASY = 1` | Easy |
 | `SAWGameDifficultyType.MEDIUM = 2` | Medium |
 | `SAWGameDifficultyType.HARD = 3` | Hard |
+
+***
+
+### voyager\_seed\_window\_min?
+
+> `optional` **voyager\_seed\_window\_min?**: `number`
+
+Minutes for the Voyager seed window.
+The seed window is the range of seeds that can be used to generate the map.
+The seed window is used to ensure that the map is generated the same way for each player.

package/docs/api/interfaces/TAchCategory.md

@@ -1,6 +1,14 @@
 # Interface: TAchCategory
 
-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.
 
 ## Properties
 
@@ -8,7 +16,8 @@ TAchCategory describes the badge category item. Each badge item can be assigned
 
 > **id**: `number`
 
-ID of the badge category
+Stable numeric ID of the category. Used as the key when joining to
+`TMissionOrBadge.category_ids: number[]`.
 
 ***
 
@@ -16,7 +25,10 @@ ID of the badge category
 
 > **name**: `string`
 
-Name of the badge category
+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.
 
 ***
 
@@ -24,4 +36,7 @@ Name of the badge category
 
 > **order**: `number`
 
-Order of the badge category among other categories. Default value is 1
+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
+operator did not configure an explicit order.

package/docs/api/interfaces/TBuyStoreItemResult.md

@@ -6,15 +6,29 @@
 
 > **err\_code**: [`BuyStoreItemErrorCode`](../enumerations/BuyStoreItemErrorCode.md)
 
-Error code representing the result of the purchase of the shop item. Successful purchase if err_code is 0 
+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:
-```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
-  }
-});
+```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);
+}
 ```
 
 ***
@@ -23,4 +37,8 @@ SmarticoAPI.buyStoreItem(item_id).then(res => {
 
 > **err\_message**: `string`
 
-Optional error message
+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.

package/docs/api/interfaces/TMissionClaimRewardResult.md

@@ -1,6 +1,9 @@
 # Interface: TMissionClaimRewardResult
 
-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.
 
 ## Properties
 
@@ -8,7 +11,15 @@ TMissionClaimRewardResult describes the response of call to _smartico.api.reques
 
 > **err\_code**: `number`
 
-Error code that represents outcome of the claim request. Successful claim reward in case err_code is 0
+Error code that represents outcome of the claim request.
+`0` = success (rewards have been credited);
+`40017` = already claimed (treat as idempotent success);
+`40015` = claim window expired;
+`40016` = mission not completed yet (stale local state);
+`1` = generic server error (stale `ach_completed_id`, archived/draft
+mission, label mismatch, completion older than 6 months, or
+`requires_prize_claim=false` on the server). See
+`requestMissionClaimReward` TSDoc for the full table.
 
 ***
 
@@ -16,4 +27,4 @@ Error code that represents outcome of the claim request. Successful claim reward
 
 > **err\_message**: `string`
 
-Optional error message
+Optional error message; populated on non-zero `err_code`.

package/docs/api/interfaces/TMissionOptInResult.md

@@ -1,6 +1,9 @@
 # Interface: TMissionOptInResult
 
-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.
 
 ## Properties
 
@@ -8,7 +11,11 @@ TMissionOptInResult describes the response of call to _smartico.api.requestMissi
 
 > **err\_code**: `number`
 
-Error code that represents outcome of the opt-in request. Successful opt-in in case err_code is 0
+Error code. `0` = success; `40010` = already opted-in (treat as
+idempotent success); `40013` = mission not opt-in-able (draft /
+archived / out of window); `40014` = locked (show unlock tasks);
+`105` = wrong id or visibility-condition rejection. See
+`requestMissionOptIn` TSDoc for the full table.
 
 ***
 
@@ -16,4 +23,4 @@ Error code that represents outcome of the opt-in request. Successful opt-in in c
 
 > **err\_message**: `string`
 
-Optional error message
+Optional error message; populated on non-zero `err_code`.

package/docs/api/interfaces/TMissionOrBadge.md

@@ -236,7 +236,11 @@ The ribbon of the mission/badge item. Can be 'sale', 'hot', 'new', 'vip' or URL
 
 > `optional` **ach\_completed\_id?**: `number`
 
-ID of the completion fact from ach_completed or ach_completed_recurring tables
+Stable identifier of the specific completion of this mission. Pass this
+value to `requestMissionClaimReward()` alongside the mission id. Always
+read from a fresh `getMissions()` result; never synthesise or cache
+across sessions. Undefined for badges and for missions that have not
+yet completed.
 
 ***
 
@@ -363,7 +367,7 @@ The date/timestamp indicating when the mission claim will expire
 
 ### prize\_claim\_period\_type\_id?
 
-> `optional` **prize\_claim\_period\_type\_id?**: `AchievementClaimPeriodTypeId`
+> `optional` **prize\_claim\_period\_type\_id?**: [`AchievementClaimPeriodTypeId`](../enumerations/AchievementClaimPeriodTypeId.md)
 
 The type of the prize claim period (Relative or Exact time and date)
 

package/docs/api/interfaces/TStoreItem.md

@@ -125,7 +125,19 @@ The list of IDs of the categories where the store item is assigned, information
 
 > `optional` **pool?**: `number`
 
-Number of items in the pool avaliable for the purchase.
+Number of items remaining in the pool available for purchase.
+`null` means unlimited supply (no pool configured for this item).
+A positive integer is the remaining stock.
+`0` means sold out — the item is still returned by `getStoreItems` so a
+"Sold out" state can be rendered. Operators may instead choose to hide
+pool-empty items entirely (per-item operator flag), in which case
+sold-out items simply disappear from the catalog rather than appearing
+with `pool === 0`.
+
+Pool is decremented server-side on a successful purchase; the client
+observes the new value via the `onUpdate` callback on `getStoreItems`
+(which fires only for the buyer's own purchases — other users'
+concurrent purchases do not push).
 
 ***
 
@@ -201,6 +213,14 @@ The date when the store item will be available till
 
 ***
 
+### show\_timer?
+
+> `optional` **show\_timer?**: `boolean`
+
+Should countdown timer be shown when `active_till_date` is present
+
+***
+
 ### discounted\_price?
 
 > `optional` **discounted\_price?**: `number`

package/docs/api/interfaces/TTournamentDetailed.md

@@ -707,6 +707,10 @@ Per-clan prize structure; null for non-clan tournaments
 
 > **prize\_pool\_amount**: `number`
 
+#### prize\_pool\_currency\_code
+
+> **prize\_pool\_currency\_code**: `string`
+
 #### activity\_type\_id
 
 > **activity\_type\_id**: `number`
@@ -731,6 +735,10 @@ Per-clan prize structure; null for non-clan tournaments
 
 > **image\_url**: `string`
 
+##### public\_meta.prize\_name?
+
+> `optional` **prize\_name?**: `string`
+
 #### tiers
 
 > **tiers**: `object`[]