@smartico/public-api 0.0.380 → 0.0.382

package/docs/api/documents/Transforms.md

@@ -0,0 +1,99 @@
+# Transform functions — raw protocol → friendly types
+
+The SDK talks to the Smartico backend over a low-level WebSocket protocol (the
+raw request/response messages documented in the Native Protocol doc, `docs/native/PROTOCOL.md`).
+Those raw messages are shaped for the wire, not for application developers —
+they nest display fields inside `public_meta` / `*PublicMeta` objects, mix
+camelCase and snake_case, carry opaque numeric type ids, JSON-encode some
+values as strings, and include wire-only fields a UI never needs.
+
+Rather than hand all that to the consumer, the SDK runs a **transform function**
+over every response, producing a clean, consistently-shaped, friendly object.
+This is why `_smartico.api.*` returns pleasant `T`-prefixed types instead of
+the raw protocol shapes.
+
+## The three naming conventions
+
+You'll see this pattern repeated across every domain:
+
+| Convention | Where | Meaning |
+|---|---|---|
+| **`T`-prefixed types** (`TStoreItem`, `TAvatarDefinition`, `TClanInfo`, `TMissionOrBadge`, …) | `WSAPITypes.ts` + domain folders | The **friendly** result type returned to the consumer. The `T` distinguishes it from the raw protocol type of the same name (`StoreItem`, `AvatarDefinition`, …). |
+| **`*Transform` functions** (`StoreItemTransform`, `avatarDefinitionTransform`, `clanTournamentPlayersTransform`, …) | `src/<Domain>/*.ts` | Pure functions that map one raw protocol entity to its friendly `T` type. ~30 of them, one per entity. |
+| **`*T` methods** (`storeGetItemsT`, `avatarsGetListT`, `clansGetListT`, …) | `SmarticoAPI` | The "**T**ransformed" variant of a protocol call: send the raw request, then run the matching transform on the response. The `_smartico.api.*` surface is built on these. |
+
+**As a consumer you never call transforms directly** — `_smartico.api.*`
+already returns the transformed `T` types. The transforms are the SDK internals
+that produce them. (They are exported from the package, so you *can* reference
+them, but you rarely need to.)
+
+## What a transform actually does
+
+Transforms normalize the raw shape in a handful of recurring ways:
+
+1. **Flatten nested metadata** — raw entities bury display fields inside a
+   `public_meta` / `*PublicMeta` sub-object; the transform lifts them to the
+   top level. (`item.itemPublicMeta.name` → `item.name`.)
+2. **Normalize casing** — raw fields are inconsistently camelCase
+   (`userId`, `userAltName`, `isMe`, `canBuy`); the friendly types are
+   consistent snake_case (`user_id`, `public_username`, `is_me`, `can_buy`).
+3. **Compute convenience fields** — e.g. build an absolute `avatar_url` from a
+   relative image path plus the label's avatar domain, so the consumer can use
+   it directly in an `<img>`.
+4. **Resolve opaque ids to named values** — numeric type ids become named enum
+   values (e.g. a raw `itemTypeId` becomes a friendly `type`).
+5. **Parse string-encoded JSON** — fields the server sends as JSON strings
+   (e.g. `custom_data`) are parsed into real objects.
+6. **Drop wire-only / internal fields and junk rows** — the friendly type keeps
+   only what a UI needs.
+
+## Before / after example
+
+Raw `AvatarDefinition` on the wire (`GET_AVATARS_LIST_RESPONSE`):
+
+```json
+{
+  "avatar_real_id": 7,
+  "priority": 2,
+  "public_meta": { "description": "Knight", "url": "avatars/knight.png" },
+  "avatar_source_type_id": 0,
+  "is_given": true,
+  "is_in_use": false
+}
+```
+
+Friendly `TAvatarDefinition` returned by `_smartico.api.getAvatarsList()`:
+
+```json
+{
+  "avatar_real_id": 7,
+  "priority": 2,
+  "description": "Knight",
+  "url": "avatars/knight.png",
+  "avatar_url": "https://<avatar-domain>/avatars/knight.png",
+  "avatar_source_type_id": 0,
+  "is_given": true,
+  "is_in_use": false
+}
+```
+
+The transform flattened `public_meta.description` / `public_meta.url` to the top
+level and added the computed absolute `avatar_url`.
+
+Casing normalization is most visible in clan-tournament players — the raw
+`players[]` use `userId` / `userAltName` / `isMe`, which the transform renames
+to `user_id` / `public_username` / `is_me`.
+
+## Why this matters for native clients
+
+Native clients (Kotlin / Swift) that speak the WebSocket protocol directly —
+see the Native Protocol doc (`docs/native/PROTOCOL.md`) — receive the **raw**
+shapes, not the transformed `T` types. PROTOCOL.md documents those raw shapes precisely
+(nested `public_meta`, camelCase player fields, etc.) and flags where the JS SDK
+adds a computed field (such as `avatar_url`). A native client is responsible for
+doing the equivalent normalization itself if it wants the friendlier shape.
+
+In short:
+
+- **JS / browser SDK** → call `_smartico.api.*`, get friendly `T` types (transforms applied for you).
+- **Native client** → use the raw protocol from PROTOCOL.md, apply your own mapping.

package/docs/api/enumerations/BonusStatus-1.md

@@ -1,12 +1,17 @@
 # Enumeration: BonusStatus
 
+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`.
+
 ## Enumeration Members
 
 ### New
 
 > **New**: `1`
 
-The bonus is newly created (shouldn't be shown to the client)
+Newly created, not yet processed (internal).
 
 ***
 
@@ -14,7 +19,7 @@ The bonus is newly created (shouldn't be shown to the client)
 
 > **COUPON\_ISSUED**: `2`
 
-The bonus is issued and available for redemption but has not been redeemed yet
+Issued and awaiting player claim.
 
 ***
 
@@ -22,7 +27,7 @@ The bonus is issued and available for redemption but has not been redeemed yet
 
 > **REDEEMED**: `3`
 
-The bonus has been successfully redeemed
+Successfully redeemed.
 
 ***
 
@@ -30,7 +35,7 @@ The bonus has been successfully redeemed
 
 > **REDEEM\_FAILED**: `4`
 
-The bonus is still valid, but a previous redemption attempt failed
+Previous redemption attempt failed; still valid and re-claimable.
 
 ***
 
@@ -38,7 +43,7 @@ The bonus is still valid, but a previous redemption attempt failed
 
 > **COUPON\_ISSUE\_FAILED**: `5`
 
-Failed to issue the bonus (shouldn't be shown to the client)
+Coupon issuance failed (internal).
 
 ***
 
@@ -46,4 +51,4 @@ Failed to issue the bonus (shouldn't be shown to the client)
 
 > **EXPIRED**: `6`
 
-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).

package/docs/api/enumerations/JoinClanErrorCode.md

@@ -0,0 +1,81 @@
+# Enumeration: JoinClanErrorCode
+
+## Enumeration Members
+
+### JOIN\_CLAN\_OK
+
+> **JOIN\_CLAN\_OK**: `0`
+
+No error, join completed
+
+***
+
+### JOIN\_CLAN\_INVALID\_PARAMETERS
+
+> **JOIN\_CLAN\_INVALID\_PARAMETERS**: `1000`
+
+Invalid parameters
+
+***
+
+### JOIN\_CLAN\_NOT\_FOUND
+
+> **JOIN\_CLAN\_NOT\_FOUND**: `1001`
+
+clan_id doesn't exist for this label
+
+***
+
+### JOIN\_CLAN\_FULL
+
+> **JOIN\_CLAN\_FULL**: `1002`
+
+members_count >= capacity_limit
+
+***
+
+### JOIN\_CLAN\_INSUFFICIENT\_FUNDS
+
+> **JOIN\_CLAN\_INSUFFICIENT\_FUNDS**: `1003`
+
+Not enough Points / Gems / Diamonds for entry fee
+
+***
+
+### JOIN\_CLAN\_SEGMENT\_MISMATCH
+
+> **JOIN\_CLAN\_SEGMENT\_MISMATCH**: `1004`
+
+User doesn't satisfy entry_conditions / entry_segment_id
+
+***
+
+### JOIN\_CLAN\_USER\_IS\_NOT\_IN\_CLAN
+
+> **JOIN\_CLAN\_USER\_IS\_NOT\_IN\_CLAN**: `1005`
+
+User is not in a clan
+
+***
+
+### JOIN\_CLAN\_COOLDOWN\_ACTIVE
+
+> **JOIN\_CLAN\_COOLDOWN\_ACTIVE**: `1006`
+
+User is within the CLAN_COOLDOWN_DAYS window
+
+***
+
+### JOIN\_CLAN\_ARCHIVED
+
+> **JOIN\_CLAN\_ARCHIVED**: `1007`
+
+clan_status_id != 1 (clan is archived)
+
+***
+
+### JOIN\_CLAN\_JOINED\_AFTER\_TOURNAMENT\_START
+
+> **JOIN\_CLAN\_JOINED\_AFTER\_TOURNAMENT\_START**: `1011`
+
+Clan joined after tournament start

package/docs/api/enumerations/TournamentRegistrationError.md

@@ -59,3 +59,15 @@
 ### TOURNAMENT\_MAX\_REGISTRATIONS\_REACHED
 
 > **TOURNAMENT\_MAX\_REGISTRATIONS\_REACHED**: `30008`
+
+***
+
+### TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_GEMS
+
+> **TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_GEMS**: `30010`
+
+***
+
+### TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_DIAMONDS
+
+> **TOURNAMENT\_REGISTRATION\_NOT\_ENOUGH\_DIAMONDS**: `30011`

package/docs/api/functions/clanTournamentPlayersTransform.md

@@ -0,0 +1,13 @@
+# Function: clanTournamentPlayersTransform()
+
+> **clanTournamentPlayersTransform**(`response`): [`TClanTournamentPlayersResult`](../interfaces/TClanTournamentPlayersResult.md)
+
+## Parameters
+
+### response
+
+[`GetClanTournamentPlayersResponse`](../interfaces/GetClanTournamentPlayersResponse.md)
+
+## Returns
+
+[`TClanTournamentPlayersResult`](../interfaces/TClanTournamentPlayersResult.md)

package/docs/api/interfaces/AvatarCustomized.md

@@ -0,0 +1,25 @@
+# Interface: AvatarCustomized
+
+## Properties
+
+### avatar\_real\_id
+
+> **avatar\_real\_id**: `number`
+
+The avatar real id that this customization belongs to
+
+***
+
+### url
+
+> **url**: `string`
+
+CDN URL of the AI-customized avatar image
+
+***
+
+### dt\_created
+
+> **dt\_created**: `string`
+
+ISO date string when the customization was created

package/docs/api/interfaces/AvatarDefinition.md

@@ -0,0 +1,94 @@
+# Interface: AvatarDefinition
+
+## Properties
+
+### avatar\_real\_id
+
+> **avatar\_real\_id**: `number`
+
+Unique identifier of the avatar
+
+***
+
+### is\_default
+
+> **is\_default**: `boolean`
+
+Whether this avatar is the default one
+
+***
+
+### hide\_until\_achieved
+
+> **hide\_until\_achieved**: `boolean`
+
+If true, avatar is hidden until user achieves/unlocks it
+
+***
+
+### priority
+
+> **priority**: `number`
+
+Display priority — lower value means higher position
+
+***
+
+### public\_meta
+
+> **public\_meta**: `object`
+
+Public metadata containing the avatar image URL and optional description
+
+#### description?
+
+> `optional` **description?**: `string`
+
+Optional description of the avatar
+
+#### url
+
+> **url**: `string`
+
+Image path/URL of the avatar
+
+***
+
+### avatar\_source\_type\_id
+
+> **avatar\_source\_type\_id**: `number`
+
+Source type of the avatar.
+0 = free (always available), other values = earned/purchased
+
+***
+
+### active\_from\_date?
+
+> `optional` **active\_from\_date?**: `string`
+
+ISO date string from which the avatar becomes available
+
+***
+
+### active\_till\_date?
+
+> `optional` **active\_till\_date?**: `string`
+
+ISO date string until which the avatar is available
+
+***
+
+### is\_given
+
+> **is\_given**: `boolean`
+
+Whether the avatar has been granted/given to the current user
+
+***
+
+### is\_in\_use?
+
+> `optional` **is\_in\_use?**: `boolean`
+
+Whether this avatar is currently in use by the user

package/docs/api/interfaces/AvatarPrompt.md

@@ -0,0 +1,45 @@
+# Interface: AvatarPrompt
+
+## Properties
+
+### prompt\_id
+
+> **prompt\_id**: `number`
+
+Unique identifier of the AI customization prompt
+
+***
+
+### public\_meta
+
+> **public\_meta**: `object`
+
+Public metadata for the prompt
+
+#### name
+
+> **name**: `string`
+
+Display name of the prompt style (e.g. "Cartoon", "Watercolor")
+
+#### icon\_url
+
+> **icon\_url**: `string`
+
+URL of the prompt style icon image
+
+***
+
+### cost\_currency\_type\_id
+
+> **cost\_currency\_type\_id**: `number`
+
+Currency type used to pay for this customization (0=points, 1=gems, 2=diamonds)
+
+***
+
+### cost\_value
+
+> **cost\_value**: `number`
+
+Cost amount in the given currency

package/docs/api/interfaces/BonusMetaMap-1.md

@@ -1,9 +1,12 @@
 # Interface: BonusMetaMap
 
+Instance-level bonus display metadata (set per-issuance, may carry
+a dynamically-computed amount).
+
 ## Properties
 
 ### uiAmount?
 
 > `optional` **uiAmount?**: `string`
 
-Label and description of the bonus sent to the player
+Display-ready amount string (e.g. "€50", "100 free spins").

package/docs/api/interfaces/BonusTemplateMetaMap-1.md

@@ -1,12 +1,15 @@
 # Interface: BonusTemplateMetaMap
 
+Template-level bonus display metadata (operator-configured at the
+bonus template; identical for every bonus issued from the same template).
+
 ## Properties
 
 ### description
 
 > **description**: `string`
 
-Description of the bonus template
+Operator-set description / display text. May include HTML.
 
 ***
 
@@ -14,7 +17,8 @@ Description of the bonus template
 
 > **acknowledge**: `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.
 
 ***
 
@@ -22,7 +26,7 @@ Acknowledge message setup in the bonus template
 
 > **image\_url**: `string`
 
-Image URL of the bonus template, 1:1 aspect ratio
+Bonus icon URL (1:1 aspect ratio recommended).
 
 ***
 
@@ -30,4 +34,5 @@ Image URL of the bonus template, 1:1 aspect ratio
 
 > `optional` **redirect\_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).

package/docs/api/interfaces/Clan.md

@@ -1,5 +1,9 @@
 # Interface: Clan
 
+## Extended by
+
+- [`ClanInfo`](ClanInfo.md)
+
 ## Properties
 
 ### clan\_id

package/docs/api/interfaces/ClanInfo.md

@@ -0,0 +1,109 @@
+# Interface: ClanInfo
+
+## Extends
+
+- [`Clan`](Clan.md)
+
+## Properties
+
+### clan\_id
+
+> **clan\_id**: `number`
+
+#### Inherited from
+
+[`Clan`](Clan.md).[`clan_id`](Clan.md#clan_id)
+
+***
+
+### public\_meta
+
+> **public\_meta**: [`ClanPublicMeta`](ClanPublicMeta.md)
+
+#### Inherited from
+
+[`Clan`](Clan.md).[`public_meta`](Clan.md#public_meta)
+
+***
+
+### member\_count
+
+> **member\_count**: `number`
+
+#### Inherited from
+
+[`Clan`](Clan.md).[`member_count`](Clan.md#member_count)
+
+***
+
+### capacity\_limit
+
+> **capacity\_limit**: `number`
+
+#### Inherited from
+
+[`Clan`](Clan.md).[`capacity_limit`](Clan.md#capacity_limit)
+
+***
+
+### entry\_fee\_currency\_type\_id
+
+> **entry\_fee\_currency\_type\_id**: `number`
+
+ShopPurchaseType: 0=Points, 1=Gems, 2=Diamonds, 3=Free
+
+#### Inherited from
+
+[`Clan`](Clan.md).[`entry_fee_currency_type_id`](Clan.md#entry_fee_currency_type_id)
+
+***
+
+### entry\_fee\_amount
+
+> **entry\_fee\_amount**: `number`
+
+#### Inherited from
+
+[`Clan`](Clan.md).[`entry_fee_amount`](Clan.md#entry_fee_amount)
+
+***
+
+### rating\_position
+
+> **rating\_position**: `number`
+
+F1 rank ASC, 1=best
+
+#### Inherited from
+
+[`Clan`](Clan.md).[`rating_position`](Clan.md#rating_position)
+
+***
+
+### rating\_score
+
+> **rating\_score**: `number`
+
+#### Inherited from
+
+[`Clan`](Clan.md).[`rating_score`](Clan.md#rating_score)
+
+***
+
+### label\_id
+
+> **label\_id**: `number`
+
+***
+
+### members
+
+> **members**: [`ClanMember`](ClanMember.md)[]
+
+***
+
+### cooldown\_until
+
+> **cooldown\_until**: `string`
+
+Cooldown until date string; null if no cooldown active

package/docs/api/interfaces/ClanMember.md

@@ -0,0 +1,53 @@
+# Interface: ClanMember
+
+## Properties
+
+### user\_id
+
+> **user\_id**: `number`
+
+***
+
+### public\_username
+
+> **public\_username**: `string`
+
+***
+
+### avatar\_id
+
+> **avatar\_id**: `string`
+
+***
+
+### avatar\_real\_id
+
+> **avatar\_real\_id**: `number`
+
+***
+
+### position
+
+> **position**: `number`
+
+Rank within clan
+
+***
+
+### contribution\_score
+
+> **contribution\_score**: `number`
+
+Aggregated tournament contribution
+
+***
+
+### is\_me?
+
+> `optional` **is\_me?**: `boolean`
+
+***
+
+### clean\_ext\_user\_id?
+
+> `optional` **clean\_ext\_user\_id?**: `string`