@smartico/public-api 0.0.386 → 0.0.388

package/docs/SmarticoObject.md

@@ -108,6 +108,14 @@ login payload and (optionally) the language. Both are being consolidated into
 Logs the current user out, forgets the session, and reconnects as anonymous.
 Fires the `logout` callback on success.
 
+### `checkSuccessfullyIdentify()`
+
+Returns `true` once the SDK is initialized **and** a user has been
+successfully identified, `false` otherwise. Use it as a synchronous gate
+before calling user-scoped `_smartico.api.*` methods (e.g. `getUserProfile()`),
+as an alternative to waiting on the `identify` callback. Returns `false` in
+visitor mode.
+
 ### `changeLanguage(language)`
 
 Switches the active language. The code is normalized to a 2-letter form
@@ -396,6 +404,13 @@ Returns `true` on mobile user agents.
 Parse the current page URL / URL hash into an object (helpers for reading
 query / hash parameters).
 
+### `sendServerError(message)` · `sendServerDebug(message)`
+
+Forward a client-side message to Smartico's servers for support correlation —
+`sendServerError` for error conditions, `sendServerDebug` for diagnostic
+detail. Useful when reporting an integration issue so the message lands
+alongside your session server-side. No-ops if the SDK isn't initialized.
+
 ---
 
 ## Setup notes

package/docs/api/README.md

@@ -10,6 +10,7 @@
 
 - [PointChangeSourceType](enumerations/PointChangeSourceType.md)
 - [UserBalanceType](enumerations/UserBalanceType.md)
+- [AvatarCustomizeErrorCode](enumerations/AvatarCustomizeErrorCode.md)
 - [BonusStatus](enumerations/BonusStatus.md)
 - [JoinClanErrorCode](enumerations/JoinClanErrorCode.md)
 - [ActivityTypeLimited](enumerations/ActivityTypeLimited.md)
@@ -78,6 +79,7 @@
 
 - [PointsLog](interfaces/PointsLog.md)
 - [GemsDiamondsLog](interfaces/GemsDiamondsLog.md)
+- [AvatarCustomizeResponse](interfaces/AvatarCustomizeResponse.md)
 - [AvatarCustomized](interfaces/AvatarCustomized.md)
 - [AvatarDefinition](interfaces/AvatarDefinition.md)
 - [AvatarPrompt](interfaces/AvatarPrompt.md)

package/docs/api/classes/WSAPIAvatars.md

@@ -342,3 +342,138 @@ switch (r.err_code) {
 ```
 
 ***
+
+### avatarsCustomize()
+
+> **avatarsCustomize**(`props`): `Promise`\<[`AvatarCustomizeResponse`](../interfaces/AvatarCustomizeResponse.md)\>
+
+Generates an AI-customized variant of a base avatar by applying an
+operator-defined style prompt, returning the CDN URL of the result.
+This is a paid, generate-only step: it does NOT change the user's
+active avatar — pass the returned `cdn_url` to [setAvatar](#setavatar) to
+activate it.
+
+#### Parameters
+
+##### props
+
+###### label_id
+
+`number`
+
+Numeric Smartico label (brand) ID the user belongs to.
+
+###### user_id
+
+`number`
+
+Numeric Smartico user ID.
+
+###### prompt_id
+
+`number`
+
+Style-prompt ID (`prompt_id`) from [getAvatarPrompts](#getavatarprompts).
+
+###### avatar_url
+
+`string`
+
+CDN URL of the base avatar to customize.
+
+###### avatar_real_id
+
+`number`
+
+`avatar_real_id` of the base avatar.
+
+#### Returns
+
+`Promise`\<[`AvatarCustomizeResponse`](../interfaces/AvatarCustomizeResponse.md)\>
+
+[AvatarCustomizeResponse](../interfaces/AvatarCustomizeResponse.md) — `cdn_url` set on success;
+         `errCode` / `errMessage` set on failure.
+
+#### Remarks
+
+**Preconditions**
+- Authenticated session required; not available in visitor mode (throws).
+- All five fields are mandatory — the SDK throws synchronously
+  (`Error("<field> is required")`) if any is missing or zero.
+- `prompt_id` must be one of the prompts from [getAvatarPrompts](#getavatarprompts);
+  `avatar_url` / `avatar_real_id` identify the base avatar to style.
+
+**Cost**
+Each generation costs the currency the operator configured on the
+chosen prompt (points, gems, or diamonds — some prompts are free; read
+`cost_currency_type_id` / `cost_value` from the [getAvatarPrompts](#getavatarprompts)
+entry to gate the UI before calling). The cost is charged only on
+success; if the user can't afford it the call fails with `errCode -1`
+and nothing is generated or charged.
+
+**Latency**
+Generation runs server-side AI image synthesis and is synchronous from
+the caller's side — expect several seconds (roughly 5–20 s) before the
+promise resolves. There is no SDK cache and no push/subscription; show
+a loading state for the full duration and disable the trigger to
+prevent duplicate submissions.
+
+**Result & error codes**
+On success the result has `cdn_url` set; on failure it has `errCode` /
+`errMessage` set and no `cdn_url`. Branch on `errCode` — the generic
+message is fixed text, not cause-specific:
+- `12001` (`AvatarCustomizeErrorCode.AVATAR_USER_LIMIT`) — the user hit
+  their monthly per-user generation cap. Nothing is generated or charged.
+- `12002` (`AvatarCustomizeErrorCode.AVATAR_LABEL_LIMIT`) — the brand's
+  shared monthly pool is exhausted. Nothing is generated or charged;
+  surface a "try again later" message.
+- `-1` — generic failure: insufficient balance, an unavailable prompt,
+  or a generation error. Nothing is charged. Allow the user to retry.
+
+Both monthly caps are operator-configured and reset at the start of
+each calendar month.
+
+**Side effects (on success)**
+The generated variant is persisted to the user's customization history
+and counts toward the monthly caps **whether or not** it is later
+activated — generation is not reversible. The SDK clears the
+[getAvatarsCustomized](#getavatarscustomized) cache so the next call surfaces the new
+variant. The user's active avatar is unchanged until you call
+[setAvatar](#setavatar) with the returned `cdn_url`.
+
+**Idempotency**: not idempotent — each successful call generates (and
+charges for) a new variant. Guard the call site against double-clicks.
+
+**UI guidance**: see [UI Guide — `avatarsCustomize`](../_media/UIGuide_avatarsCustomize.md).
+
+**Visitor mode**: not supported (throws).
+
+#### Example
+
+```ts
+// label_id / user_id identify the Smartico user being customized.
+const prompts = await window._smartico.api.getAvatarPrompts();
+const prompt = prompts[0];
+
+console.log('[smartico] generating avatar — show a spinner for ~5-20s and disable the Generate button');
+const result = await window._smartico.api.avatarsCustomize({
+  label_id,
+  user_id,
+  prompt_id: prompt.prompt_id,
+  avatar_url: baseAvatar.avatar_url,
+  avatar_real_id: baseAvatar.avatar_real_id,
+});
+
+if (result.cdn_url) {
+  console.log('[smartico] generation succeeded — preview this URL, then call setAvatar to apply it:', result.cdn_url);
+  // await window._smartico.api.setAvatar({ avatar_url: result.cdn_url, avatar_real_id: baseAvatar.avatar_real_id });
+} else if (result.errCode === 12001) {
+  console.error('[smartico] user monthly limit reached — show "you have used all your custom avatars this month"');
+} else if (result.errCode === 12002) {
+  console.error('[smartico] brand monthly pool exhausted — show "custom avatars are unavailable right now, try later"');
+} else {
+  console.error('[smartico] generation failed (e.g. not enough balance) — let the user retry:', result.errMessage);
+}
+```
+
+***

package/docs/api/classes/WSAPIClans.md

@@ -334,12 +334,10 @@ below.
   tournament requires the user to be in a clan first.
 - `1006` (`JOIN_CLAN_COOLDOWN_ACTIVE`) — user is inside the
   switch-cooldown window from a previous clan join (default
-  7 days, configurable per label). Surface the
+  7 days, configurable per label). Only reachable when the user is
+  already in a *different* clan (this call is then a clan switch);
+  a first-time join never returns `1006`. Surface the
   `TClans.cooldown_until` expiry in the disabled CTA.
-- `1007` (`JOIN_CLAN_ARCHIVED`) — defined on the public enum but
-  the server does NOT emit this code in practice (archived clans
-  are reported as `1001`). Handle it as a synonym for `1001`
-  defensively, but do not rely on it.
 - `1011` (`JOIN_CLAN_JOINED_AFTER_TOURNAMENT_START`) — this
   method does NOT return `1011` directly. The code fires on
   [registerInTournament](WSAPITournaments.md#registerintournament) responses when the user joined

package/docs/api/classes/WSAPILeaderBoard.md

@@ -13,7 +13,9 @@ monthly tabs.
 
 The leaderboard for each period type is configured separately by
 the operator. A label may have any combination of DAILY, WEEKLY,
-and MONTHLY boards configured (or none).
+and MONTHLY boards configured (or none). To discover which boards
+exist before loading any standings, call [getLeaderBoards](#getleaderboards)
+(metadata only) and drive the tab selector from its `period_type_id`s.
 
 #### Parameters
 
@@ -29,12 +31,13 @@ The board's period type
 
 ##### getPreviousPeriod?
 
-`boolean`
+`number` \| `boolean`
 
-When `true`, returns the most recent
-                          finalized snapshot for that period type
-                          (e.g. last week's results). Defaults to
-                          `false` (current in-progress period).
+Which period to fetch. `false` (default)
+                          = current in-progress period; `true` =
+                          the most recent finalized snapshot; a
+                          number `n` = the n-th previous snapshot
+                          (`1` = previous, `2` = the one before, …).
 
 #### Returns
 
@@ -56,10 +59,13 @@ against that case in consumer code.
 Pass a `periodType` from [LeaderBoardPeriodType](../enumerations/LeaderBoardPeriodType.md)
 (`DAILY = 1`, `WEEKLY = 2`, `MONTHLY = 3`). Pass
 `getPreviousPeriod: true` to fetch the most-recently-ended
-period's snapshot (yesterday's results, last week's results,
-last month's results) instead of the current live period. The
-SDK only exposes one period back — older snapshots are not
-reachable through this method.
+period's snapshot (yesterday's / last week's / last month's
+results) instead of the current live period. To reach older
+snapshots, pass a number instead of a boolean: `1` = previous
+period, `2` = the one before that, and so on (`0` / `false` =
+current). Use the snapshot's `create_date` / `version_id` to label
+which historical run a previous-period board is. How far back
+snapshots are retained is operator-configured.
 
 **Top-20 cap**
 The server hard-caps `users[]` at 20 entries, ordered by
@@ -147,3 +153,73 @@ console.log('[smartico] previous-week standings — render with greyed-out "ende
 ```
 
 ***
+
+### getLeaderBoards()
+
+> **getLeaderBoards**(): `Promise`\<[`LeaderBoardDetailsT`](../interfaces/LeaderBoardDetailsT.md)[]\>
+
+Returns the list of leaderboards the operator has configured for this
+label — **metadata only, without participants**. Use it to discover
+which boards exist (and their period types) so you can render the
+board/tab selector, then load a specific board's standings on demand
+with [getLeaderBoard](#getleaderboard).
+
+This is the lightweight discovery counterpart to [getLeaderBoard](#getleaderboard):
+it issues one round-trip that returns every board's identity, name,
+description, rules, `period_type_id`, and prize table, but **not** the
+ranked players. Fetching the full standings for one board (the top-20
+`users[]` and the caller's own `me` entry) is what [getLeaderBoard](#getleaderboard)
+does per period.
+
+#### Returns
+
+`Promise`\<[`LeaderBoardDetailsT`](../interfaces/LeaderBoardDetailsT.md)[]\>
+
+Promise resolving to the array of configured boards
+         (metadata only). Empty array when none are configured.
+
+#### Remarks
+
+**Returned shape**
+An array of `LeaderBoardDetailsT`, one per configured board, ordered by
+`period_type_id` ascending (DAILY, WEEKLY, MONTHLY, …). On every entry
+`users` is an empty array and `me` is `undefined` — this call never
+carries participant data. Read `period_type_id` from each entry and pass
+it to [getLeaderBoard](#getleaderboard) to load that board's standings.
+
+**Empty result**
+Resolves to an empty array when the label has no leaderboards configured
+— treat that as "hide the leaderboard surface".
+
+**Cache TTL**
+Cached for 30 seconds under a dedicated key (independent of
+[getLeaderBoard](#getleaderboard)'s per-period cache). Repeated calls within the
+window return the cached list without a round-trip.
+
+**Refresh model**: one-shot fetch — no subscription, no push. Board
+configuration changes surface on the next cache miss.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**Visitor mode**: supported. Returns the brand's public board list.
+
+#### Example
+
+```ts
+const boards = await window._smartico.api.getLeaderBoards();
+
+if (boards.length === 0) {
+  console.log('[smartico] no leaderboards configured — hide the leaderboard surface');
+  return;
+}
+
+// Render one tab per board from the lightweight list (no players yet).
+console.log('[smartico] render leaderboard tabs:', boards.map(b => b.name));
+
+// When the user opens a tab, load that board's standings on demand.
+const first = boards[0];
+const full = await window._smartico.api.getLeaderBoard(first.period_type_id);
+console.log('[smartico] loaded standings for', first.name, '—', full?.users.length ?? 0, 'players');
+```
+
+***

package/docs/api/documents/SmarticoObject.md

@@ -108,6 +108,14 @@ login payload and (optionally) the language. Both are being consolidated into
 Logs the current user out, forgets the session, and reconnects as anonymous.
 Fires the `logout` callback on success.
 
+### `checkSuccessfullyIdentify()`
+
+Returns `true` once the SDK is initialized **and** a user has been
+successfully identified, `false` otherwise. Use it as a synchronous gate
+before calling user-scoped `_smartico.api.*` methods (e.g. `getUserProfile()`),
+as an alternative to waiting on the `identify` callback. Returns `false` in
+visitor mode.
+
 ### `changeLanguage(language)`
 
 Switches the active language. The code is normalized to a 2-letter form
@@ -396,6 +404,13 @@ Returns `true` on mobile user agents.
 Parse the current page URL / URL hash into an object (helpers for reading
 query / hash parameters).
 
+### `sendServerError(message)` · `sendServerDebug(message)`
+
+Forward a client-side message to Smartico's servers for support correlation —
+`sendServerError` for error conditions, `sendServerDebug` for diagnostic
+detail. Useful when reporting an integration issue so the message lands
+alongside your session server-side. No-ops if the SDK isn't initialized.
+
 ---
 
 ## Setup notes

package/docs/api/enumerations/AvatarCustomizeErrorCode.md

@@ -0,0 +1,21 @@
+# Enumeration: AvatarCustomizeErrorCode
+
+Limit error codes returned in `errCode` by the `avatarsCustomize` method.
+See the `avatarsCustomize` TSDoc for the full table (including the generic
+`-1` failure, which has no named member here).
+
+## Enumeration Members
+
+### AVATAR\_USER\_LIMIT
+
+> **AVATAR\_USER\_LIMIT**: `12001`
+
+The user has reached the operator-configured per-user monthly cap on custom-avatar generations.
+
+***
+
+### AVATAR\_LABEL\_LIMIT
+
+> **AVATAR\_LABEL\_LIMIT**: `12002`
+
+The brand's operator-configured shared monthly pool of custom-avatar generations is exhausted.

package/docs/api/enumerations/JoinClanErrorCode.md

@@ -1,12 +1,17 @@
 # Enumeration: JoinClanErrorCode
 
+Error codes returned in `errCode` by the `joinClan` method (also carried
+on `TClanJoinResult`). These are terse value definitions for lookup; the
+full per-code narrative and UI handling lives in the `joinClan` method
+TSDoc, which owns the error table.
+
 ## Enumeration Members
 
 ### JOIN\_CLAN\_OK
 
 > **JOIN\_CLAN\_OK**: `0`
 
-No error, join completed
+Success — join completed; entry fee (if any) deducted.
 
 ***
 
@@ -14,7 +19,7 @@ No error, join completed
 
 > **JOIN\_CLAN\_INVALID\_PARAMETERS**: `1000`
 
-Invalid parameters
+Request was malformed (missing or invalid parameters).
 
 ***
 
@@ -22,7 +27,7 @@ Invalid parameters
 
 > **JOIN\_CLAN\_NOT\_FOUND**: `1001`
 
-clan_id doesn't exist for this label
+Clan doesn't exist for this label. Archived clans are also reported as `1001`.
 
 ***
 
@@ -30,7 +35,7 @@ clan_id doesn't exist for this label
 
 > **JOIN\_CLAN\_FULL**: `1002`
 
-members_count >= capacity_limit
+Clan is full — member capacity reached.
 
 ***
 
@@ -38,7 +43,7 @@ members_count >= capacity_limit
 
 > **JOIN\_CLAN\_INSUFFICIENT\_FUNDS**: `1003`
 
-Not enough Points / Gems / Diamonds for entry fee
+Insufficient balance for the entry fee (points / gems / diamonds).
 
 ***
 
@@ -46,7 +51,7 @@ Not enough Points / Gems / Diamonds for entry fee
 
 > **JOIN\_CLAN\_SEGMENT\_MISMATCH**: `1004`
 
-User doesn't satisfy entry_conditions / entry_segment_id
+User doesn't meet the clan's entry segment or conditions.
 
 ***
 
@@ -54,7 +59,8 @@ User doesn't satisfy entry_conditions / entry_segment_id
 
 > **JOIN\_CLAN\_USER\_IS\_NOT\_IN\_CLAN**: `1005`
 
-User is not in a clan
+User is not in a clan. Note: a `registerInTournament` response code
+that shares this enum — never returned by `joinClan`.
 
 ***
 
@@ -62,15 +68,7 @@ User is not in a clan
 
 > **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)
+User is within the clan-switch cooldown window (switch only).
 
 ***
 
@@ -78,4 +76,5 @@ clan_status_id != 1 (clan is archived)
 
 > **JOIN\_CLAN\_JOINED\_AFTER\_TOURNAMENT\_START**: `1011`
 
-Clan joined after tournament start
+Clan joined after tournament start. Note: a `registerInTournament`
+response code that shares this enum — never returned by `joinClan`.

package/docs/api/interfaces/AvatarCustomizeResponse.md

@@ -0,0 +1,31 @@
+# Interface: AvatarCustomizeResponse
+
+Result of `_smartico.api.avatarsCustomize()`. On success only `cdn_url` is
+set; on failure only `errCode` / `errMessage`.
+
+## Properties
+
+### cdn\_url?
+
+> `optional` **cdn\_url?**: `string`
+
+CDN URL of the generated avatar variant. Present on success.
+
+***
+
+### errCode?
+
+> `optional` **errCode?**: `number`
+
+Error code. Present on failure. Typed values are members of
+[AvatarCustomizeErrorCode](../enumerations/AvatarCustomizeErrorCode.md); `-1` is a generic failure. See the
+`avatarsCustomize` TSDoc for the full table.
+
+***
+
+### errMessage?
+
+> `optional` **errMessage?**: `string`
+
+Optional error message. Present on failure; the generic (`-1`) message
+is fixed text, so branch on `errCode`, not this string.

package/docs/api/interfaces/LeaderBoardDetailsT.md

@@ -46,6 +46,24 @@ Period type this board is bound to ([LeaderBoardPeriodType](../enumerations/Lead
 
 ***
 
+### version\_id
+
+> **version\_id**: `number`
+
+Snapshot version. `0` for the live current period; a positive value
+identifies a finalized previous-period snapshot (see `getPreviousPeriod`).
+
+***
+
+### create\_date
+
+> **create\_date**: `number`
+
+Snapshot creation timestamp (Unix ms). `0` for the live current period;
+the finalization time for a previous-period snapshot.
+
+***
+
 ### rewards
 
 > **rewards**: [`LeaderBoardsRewardsT`](LeaderBoardsRewardsT.md)[]
@@ -59,6 +77,7 @@ Per-place prize table; the array length is the number of paid places.
 > **users**: [`LeaderBoardUserT`](LeaderBoardUserT.md)[]
 
 Top-20 ranked entries (server-capped), sorted by `position` ASC.
+Empty when fetched via `getLeaderBoards()` (metadata-only list).
 
 ***
 

package/docs/api/interfaces/LeaderBoardUserT.md

@@ -16,7 +16,18 @@ Display username (operator-defined alias).
 
 > **avatar\_url**: `string`
 
-Resolved CDN URL for the participant's avatar.
+Resolved CDN URL for the participant's avatar. May be empty when the
+participant has no custom avatar — fall back to a level-based default
+using `level_id`.
+
+***
+
+### level\_id
+
+> **level\_id**: `number`
+
+The participant's level id — use it to resolve a level-based default
+avatar when `avatar_url` is empty.
 
 ***
 
@@ -41,4 +52,5 @@ Participant's points for this period.
 
 > **is\_me**: `boolean`
 
-`true` when this row is the current authenticated user.
+`true` when this row is the current authenticated user. Always `true`
+on the `me` entry.

package/docs/api/interfaces/TAvatarPrompt.md

@@ -33,7 +33,7 @@ Absolute CDN URL of the prompt's preview icon.
 
 > **cost\_currency\_type\_id**: `number`
 
-Currency used to pay for the customization. `0` = points, `1` = gems, `2` = diamonds.
+Currency used to pay for the customization. `0` = points, `1` = gems, `2` = diamonds, `3` = free. A `cost_value` of `0` is also free.
 
 ***
 
@@ -41,4 +41,4 @@ Currency used to pay for the customization. `0` = points, `1` = gems, `2` = diam
 
 > **cost\_value**: `number`
 
-Cost amount in the currency named by `cost_currency_type_id`.
+Cost amount in the currency named by `cost_currency_type_id`. `0` = free.

package/docs/api/interfaces/TMissionOrBadgeTask.md

@@ -44,6 +44,22 @@ Reward for completing the task in points
 
 ***
 
+### gems\_reward?
+
+> `optional` **gems\_reward?**: `number`
+
+Reward for completing the task in gems
+
+***
+
+### diamonds\_reward?
+
+> `optional` **diamonds\_reward?**: `number`
+
+Reward for completing the task in diamonds
+
+***
+
 ### execution\_count\_expected?
 
 > `optional` **execution\_count\_expected?**: `number`

package/docs/api/interfaces/UserAchievementTask.md

@@ -20,6 +20,22 @@
 
 ***
 
+### gems\_reward?
+
+> `optional` **gems\_reward?**: `number`
+
+Gems awarded when this task is completed.
+
+***
+
+### diamonds\_reward?
+
+> `optional` **diamonds\_reward?**: `number`
+
+Diamonds awarded when this task is completed.
+
+***
+
 ### task\_type\_id
 
 > **task\_type\_id**: [`AchievementTaskType`](../enumerations/AchievementTaskType.md)