@smartico/public-api 0.0.380 → 0.0.382

package/docs/api/classes/WSAPITournaments.md

@@ -3,49 +3,164 @@
 
 ### getTournamentsList()
 
-> **getTournamentsList**(`__namedParameters?`): `Promise`\<[`TTournament`](../interfaces/TTournament.md)[]\>
+> **getTournamentsList**(`params?`): `Promise`\<[`TTournament`](../interfaces/TTournament.md)[]\>
+
+Returns the list of tournaments currently visible to the user, scoped
+server-side to what the user's segments qualify them to see. Optionally
+subscribes to live updates via `onUpdate`: the callback is invoked with
+the full refreshed list whenever the user registers in a tournament.
+
+The returned list is the canonical source of truth for tournament
+lobby state (`is_user_registered`, `registration_status`,
+`is_in_progress`, `is_can_register`, etc.). Consumers should NOT
+mutate it optimistically — always wait for the `onUpdate` callback
+(or a fresh fetch after the 30 s cache window) to observe new state.
 
 #### Parameters
 
-##### \_\_namedParameters?
+##### params?
+
+Optional. Omit to fetch without subscribing.
 
 ###### onUpdate?
 
 (`data`) => `void`
 
+Callback invoked with the full refreshed
+                           tournament list after every
+                           [registerInTournament](#registerintournament) round-trip on
+                           this connection. Each call overwrites the
+                           prior callback. Never fires in visitor mode.
+
 #### Returns
 
 `Promise`\<[`TTournament`](../interfaces/TTournament.md)[]\>
 
+Promise resolving to the array of
+                           tournaments visible to the user. Empty
+                           array if no tournaments are visible.
+
+#### Remarks
+
+**Subscription model (`onUpdate`)**
+The callback receives the FULL refreshed list (never a diff/patch).
+Each subsequent call to `getTournamentsList({ onUpdate })` REPLACES
+the prior callback — only one active subscriber at a time. Pass
+`onUpdate: undefined` (or omit it) to keep the prior callback in
+place; the callback is never auto-cleared.
+
+**Update triggers** — the callback fires when:
+
+1. `registerInTournament(...)` resolves on this connection (any
+   `err_code`). The refreshed list reflects the new
+   `is_user_registered` / `registration_status` /
+   `registration_count` on the affected tournament.
+
+Does NOT fire for: tournament lifecycle transitions (start, finish,
+cancellation), score updates, other users' registrations, or
+operator-side BO edits. Those changes surface only on the next
+cache miss (after the 30 s TTL) — poll manually if your UI needs
+sub-30s lifecycle freshness.
+
+**Server-side filtering** (what's excluded before the SDK sees it)
+The server filters by visibility segment and entry segment, removes
+tournaments past their post-finish display window, and excludes
+tournaments not yet published. SDK consumers receive only items
+the user is eligible to see; no client-side gating is required.
+
+**Reading state from the returned item**
+Drive list bucketing and CTA labels from the SDK-computed booleans
+(`is_active`, `is_can_register`, `is_cancelled`, `is_finished`,
+`is_in_progress`, `is_upcoming`), NOT from raw `start_time` /
+`end_time` comparisons — the booleans encode the canonical
+lifecycle states and already reflect server-side rules around
+qualifying scores and late registration. `is_user_registered` is
+independent of `is_can_register` — a registered user has
+`is_user_registered: true` and `is_can_register: false`. The `me`
+block (if present) carries the user's own leaderboard position and
+score; it's undefined for unregistered users, users without any
+recorded score, and visitor-mode sessions. The `prize_pool_short`
+field carries the operator-supplied summary string ("$10,000",
+"Mixed prizes") for compact card rendering; the full per-place
+`prizes[]` breakdown is also populated here but is typically
+rendered only in the detail view via
+[getTournamentInstanceInfo](#gettournamentinstanceinfo).
+
+**Cross-references**
+Tournaments with `is_clan_based: true` group participants by clan —
+see [getClanTournamentPlayers](#getclantournamentplayers) for fetching the players list
+of a specific clan within a clan tournament. The detailed lobby
+view (with full player leaderboard and prize structure) comes from
+[getTournamentInstanceInfo](#gettournamentinstanceinfo). Tournaments with
+`custom_section_id` belong to an operator-defined custom section
+(resolve metadata via `getCustomSections()`).
+
+**Cache TTL**: the SDK caches the response for 30 seconds. Cache is
+fully cleared on login / logout.
+
+**Idempotency**: safe. Read-only. Repeated calls within the cache
+window return a deep-cloned cached array without a network
+round-trip.
+
+**Side effects**: none — pure metadata read.
+
+**UI guidance**: see [UI Guide — `getTournamentsList`](../_media/UIGuide_getTournamentsList.md).
+
+**Visitor mode**: supported. The same shape is returned, scoped to
+the brand's public tournament list. Per-user fields (`me`,
+`is_user_registered`, `registration_status`) are not meaningful.
+The `onUpdate` callback is accepted but never fires (registration
+mutations are not supported in visitor mode).
+
+#### Example
+
+```ts
+const tournaments = await window._smartico.api.getTournamentsList({
+  onUpdate: (refreshed) => {
+    console.log('[smartico] tournament list refreshed — re-render the lobby UI from this array, do not merge with prior state:', refreshed);
+    const justRegistered = refreshed.filter(t => t.is_user_registered);
+    console.log('[smartico] user is now registered in these tournaments:', justRegistered.map(t => t.name));
+  },
+});
+
+// Bucket items by lifecycle state for a tabbed UI.
+const live = tournaments.filter(t => t.is_in_progress);
+const upcoming = tournaments
+  .filter(t => t.is_upcoming && !t.is_user_registered)
+  .sort((a, b) => a.start_time - b.start_time);
+const mine = tournaments.filter(t => t.is_user_registered);
+const finished = tournaments.filter(t => t.is_finished);
+
+console.log('[smartico] render lobby tabs with these counts: live=', live.length,
+  'upcoming=', upcoming.length, 'mine=', mine.length, 'finished=', finished.length);
+
+// Featured tournament: pin to position 0 of the Overview/Top tabs.
+const featured = tournaments.find(t => t.is_featured && !t.is_cancelled);
+if (featured) {
+  console.log('[smartico] featured tournament — pin to position 0 of the Overview tab:', featured.name);
+}
+
+// Visitor mode: onUpdate accepted but never fires; re-poll if needed.
+// const visitorList = await window._smartico.vapi('EN').getTournamentsList();
+```
+
 ***
 
 ### 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);
-       });
-    }
-});
-```
+Returns the full detail of a single tournament instance — adds the
+player leaderboard, the full prize structure, and (for clan
+tournaments) the clan leaderboard and per-clan prize structure on
+top of everything already in `TTournament`. Use this to power a
+tournament detail / lobby screen after the user picks an item from
+[getTournamentsList](#gettournamentslist).
 
-**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);
-       });
-    }
-});
-```
+Live leaderboard updates require manual re-fetching — there is no
+subscription model, no push event, and no client-side cache (each
+call hits the server). The default Smartico UI polls every 3 seconds
+while the detail view is open.
 
 #### Parameters
 
@@ -53,19 +168,116 @@ _smartico.vapi('EN').getTournamentsList().then((result) => {
 
 `number`
 
+The `instance_id` from a `TTournament`
+                             returned by [getTournamentsList](#gettournamentslist).
+
 #### Returns
 
 `Promise`\<[`TTournamentDetailed`](../interfaces/TTournamentDetailed.md)\>
 
+Promise resolving to `TTournamentDetailed`.
+                             Rejects if the instance ID is invalid
+                             or the user lacks visibility for it.
+
+#### Remarks
+
+**Preconditions**
+Pass a valid `tournamentInstanceId` read from `TTournament.instance_id`
+on an item returned by [getTournamentsList](#gettournamentslist). The method works
+standalone — calling `getTournamentsList()` first is not required by
+the SDK, but is the only stable source of valid IDs.
+
+**Refresh model**
+- **No subscription.** This is a one-shot promise; call again to
+  refresh.
+- **No client cache.** Every call sends a network request and
+  returns the latest server snapshot. Safe to poll on an interval —
+  the default Smartico UI uses 3 s while the detail view is visible.
+- **No push event** invalidates or refreshes detail state. Score
+  changes, registration count changes, lifecycle transitions — all
+  require a fresh `getTournamentInstanceInfo` call.
+
+**Returned shape — beyond `TTournament`**
+`TTournamentDetailed` extends `TTournament` with the following
+additional data: a `players[]` leaderboard sorted server-side by
+score (only members with at least one recorded score); the user's
+own `me` block carrying their rank and score (undefined when not
+registered or when the user has no score yet); a full per-place
+`prizes[]` array (place range, type, points / gems / diamonds
+amounts, image, name); and `related_games[]` if the operator has
+associated games with this tournament. For clan tournaments
+(`is_clan_based === true`), the response also carries
+`clan_leaderboard[]` (ranked clans with `total_score` and
+`contributing_members`), `clan_prize_structure[]` (per-clan-place
+prize tiers — Fixed vs Dynamic, with ScoreWeighted /
+EqualSplit distribution for Dynamic prizes), `user_clan_id` (the
+user's own clan), and the advisory `user_position_in_clan` /
+`user_score_in_clan` fields.
+
+**Idempotency**: safe. Read-only. Each call returns the latest
+server snapshot.
+
+**Side effects**: none — pure metadata read.
+
+**UI guidance**: see [UI Guide — `getTournamentInstanceInfo`](../_media/UIGuide_getTournamentInstanceInfo.md).
+
+**Visitor mode**: not supported. Use [getTournamentsList](#gettournamentslist) for
+the public lobby list in visitor mode; the detail endpoint requires
+an authenticated session.
+
+#### Example
+
+```ts
+const tournaments = await window._smartico.api.getTournamentsList();
+const tournament = tournaments[0];
+
+console.log('[smartico] loading detail view for tournament', tournament.instance_id);
+const detail = await window._smartico.api.getTournamentInstanceInfo(tournament.instance_id);
+
+console.log('[smartico] render detail with', detail.players?.length ?? 0,
+  'players,', detail.prizes?.length ?? 0, 'prize tiers');
+
+if (detail.is_clan_based && detail.clan_leaderboard) {
+  console.log('[smartico] clan tournament — render clan leaderboard tab with',
+    detail.clan_leaderboard.length, 'clans');
+  if (detail.user_clan_id != null) {
+    console.log('[smartico] user belongs to clan', detail.user_clan_id,
+      '— highlight that row in the clan leaderboard');
+  }
+}
+
+// Live leaderboard updates — poll every 3 seconds while the detail view is open.
+const pollId = setInterval(async () => {
+  try {
+    const fresh = await window._smartico.api.getTournamentInstanceInfo(tournament.instance_id);
+    console.log('[smartico] detail refreshed — re-render player + clan leaderboards from this new snapshot:', fresh);
+  } catch (e) {
+    console.error('[smartico] tournament detail poll failed — keep showing last snapshot, retry on next tick:', e);
+  }
+}, 3_000);
+// clearInterval(pollId) when the detail view closes.
+
+if (detail.me) {
+  console.log('[smartico] current user is rank', detail.me.position,
+    'with', detail.me.scores, 'points — render the sticky "me" panel below the leaderboard');
+}
+```
+
 ***
 
 ### getClanTournamentPlayers()
 
 > **getClanTournamentPlayers**(`tournamentInstanceId`, `clanId`): `Promise`\<[`TClanTournamentPlayers`](../interfaces/TClanTournamentPlayers.md)\>
 
-Returns the players of a specific clan in a clan-based tournament.
+Returns the ranked players of a specific clan within a clan-based
+tournament instance. Used to drill down from the clan-leaderboard
+tab on the tournament detail view into a single clan's member
+roster.
 
-**Visitor mode: not supported**
+The server returns up to roughly 20 players (top-N by score
+descending). Server-side ordering is already by `scores` DESC
+(equivalent to `position` ASC) — no client-side re-sort is
+required.
 
 #### Parameters
 
@@ -73,23 +285,119 @@ Returns the players of a specific clan in a clan-based tournament.
 
 `number`
 
+The tournament `instance_id` from a
+                             clan-based `TTournament`.
+
 ##### clanId
 
 `number`
 
+The clan ID from
+                             `TTournamentDetailed.clan_leaderboard[].clan_id`.
+
 #### Returns
 
 `Promise`\<[`TClanTournamentPlayers`](../interfaces/TClanTournamentPlayers.md)\>
 
+Promise resolving to
+                             `TClanTournamentPlayers`. An invalid
+                             ID combination typically yields an
+                             empty `players` array; the SDK does
+                             not distinguish "no scores yet" from
+                             "invalid IDs" — both manifest as an
+                             empty list.
+
+#### Remarks
+
+**Preconditions**
+Pass a valid `tournamentInstanceId` (read from `TTournament.instance_id`
+returned by [getTournamentsList](#gettournamentslist)) and a `clanId` (read from
+`TTournamentDetailed.clan_leaderboard[].clan_id` returned by
+[getTournamentInstanceInfo](#gettournamentinstanceinfo)). The tournament should be
+clan-based (`is_clan_based === true`); calling this against a
+non-clan tournament typically returns an empty `players` array.
+
+**Refresh model**
+- **No subscription.** This is a one-shot promise.
+- **No client cache.** Every call hits the server.
+- **No push event** refreshes the response. Live updates to clan
+  member rankings require a fresh call.
+- The default Smartico UI fetches this once when the user opens the
+  clan-drill-down modal and does NOT refresh while the modal is
+  open. If your UI needs live updates, re-call on an interval; the
+  clan leaderboard at the parent level (via
+  [getTournamentInstanceInfo](#gettournamentinstanceinfo)) does refresh via its own
+  polling cadence.
+
+**Returned shape**
+`TClanTournamentPlayers` carries the requested clan's identity
+(`clan_id`, `clan_public_meta.name`, `clan_public_meta.image_url`)
+alongside the `players[]` array — each entry has `position`,
+`scores`, `public_username`, `clean_ext_user_id`, `avatar_id`,
+`avatar_real_id`, the resolved `avatar_url`, `user_id`, and the
+`is_me` flag identifying the current user's row. The `clan_id` and
+`clan_public_meta` on the response echo the input clan — the
+default Smartico UI ignores them and renders the header from the
+caller-side `ClanLeaderboardEntry` object, but they're available
+for consumers that don't already have that context.
+
+**Username display**: prefer `clean_ext_user_id` when set, falling
+back to `public_username`. The default Smartico UI uses
+`clean_ext_user_id || public_username || ''`.
+
+**Idempotency**: safe. Read-only. Each call returns the latest
+server snapshot.
+
+**Side effects**: none — pure metadata read.
+
+**UI guidance**: see [UI Guide — `getClanTournamentPlayers`](../_media/UIGuide_getClanTournamentPlayers.md).
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+const detail = await window._smartico.api.getTournamentInstanceInfo(tournamentInstanceId);
+if (!detail.is_clan_based || !detail.clan_leaderboard) {
+  console.log('[smartico] not a clan tournament — skip clan drill-down');
+  return;
+}
+
+// User clicked a clan row in the leaderboard.
+const clickedClan = detail.clan_leaderboard[0];
+
+console.log('[smartico] opening clan drill-down — show modal skeleton while loading');
+const result = await window._smartico.api.getClanTournamentPlayers(
+  tournamentInstanceId,
+  clickedClan.clan_id,
+);
+
+if (result.players.length === 0) {
+  console.log('[smartico] clan has no ranked players yet — render empty state ("No leaders yet")');
+} else {
+  console.log('[smartico] render clan member rows with .is-me highlight on the current user;',
+    result.players.length, 'players ranked');
+  const me = result.players.find(p => p.is_me);
+  if (me) {
+    console.log('[smartico] current user rank in this clan:', me.position, 'score:', me.scores);
+  }
+}
+```
+
 ***
 
 ### registerInTournament()
 
 > **registerInTournament**(`tournamentInstanceId`): `Promise`\<[`TTournamentRegistrationResult`](../interfaces/TTournamentRegistrationResult.md)\>
 
-Requests registration for the specified tournament instance. Returns the err_code.
+Registers the authenticated user in the specified tournament instance.
+For tournaments with a buy-in cost, the user's balance is debited
+synchronously before the response is returned; for free tournaments
+the call is a simple membership add.
 
-**Visitor mode: not supported**
+A successful response (`err_code === 0`) means the registration row
+exists server-side, the buy-in (if any) has been deducted, and the
+SDK has already triggered a refresh of the tournament lobby cache.
 
 #### Parameters
 
@@ -97,8 +405,167 @@ Requests registration for the specified tournament instance. Returns the err_cod
 
 `number`
 
+The `instance_id` from `TTournament`
+                             (NOT the template `tournament_id`).
+
 #### Returns
 
 `Promise`\<[`TTournamentRegistrationResult`](../interfaces/TTournamentRegistrationResult.md)\>
 
+`{ err_code, err_message }`; success when `err_code === 0`
+         (or `30004` when treated as idempotent no-op).
+
+#### Remarks
+
+**Preconditions**
+Read the candidate from [getTournamentsList](#gettournamentslist) and gate the call
+on `is_can_register === true`. This composite flag already encodes:
+not already registered, slot available
+(`registration_count < players_max_count`), tournament status is
+REGISTER (or STARTED with late-registration enabled), and the
+registration type is not AUTO. The SDK forwards the call
+unconditionally — calling without satisfying these will return one
+of the error codes below.
+
+For clan tournaments (`is_clan_based === true`), the user must
+already belong to a clan before calling. If they don't, prompt them
+to pick a clan first via `joinClan`, then call
+`registerInTournament` after the clan-join resolves. See "Error
+codes" `1010` below for the server-side safety net.
+
+**Error codes** (in `err_code`, typed as [TournamentRegistrationError](../enumerations/TournamentRegistrationError.md))
+- `0` — success; the registration is persisted, buy-in deducted,
+  tournament lobby refresh fires.
+- `1010` — `TOURNAMENT_USER_CANNOT_JOIN_WITHOUT_CLAN`: clan-based
+  tournament and the user has no clan. Surface the clan-pick flow
+  (e.g. open a clan-pick modal driven by `getClans` +
+  `joinClan`), then retry registration.
+- `30001` — `TOURNAMENT_INSTANCE_NOT_FOUND`: instance ID is invalid
+  or the tournament was deleted. Refresh the lobby via
+  `getTournamentsList()` and hide the entry from the UI.
+- `30002` — `TOURNAMENT_REGISTRATION_NOT_ENOUGH_POINTS`: insufficient
+  points balance for a points-cost tournament. Show an
+  insufficient-balance UI naming the deficit.
+- `30003` — `TOURNAMENT_INSTANCE_NOT_IN_STATE`: tournament is no
+  longer in a registerable state (finished, cancelled, finalizing,
+  or not yet published with late registration disabled). Refresh
+  the lobby; the button should hide.
+- `30004` — `TOURNAMENT_ALREADY_REGISTERED`: user is already
+  registered. Treat as idempotent success — hide the Register button
+  and refresh the lobby. Usually indicates a stale local state
+  (e.g. registered from another tab).
+- `30005` — `TOURNAMENT_USER_DONT_MATCH_CONDITIONS`: user fails the
+  tournament's segment / entry conditions. Prefer
+  `tournament.segment_dont_match_message` (operator-supplied) over
+  `err_message` when both are available.
+- `30006` — `TOURNAMENT_USER_NOT_REGISTERED`: anomalous on a fresh
+  register call; usually indicates a server-side race. Treat as a
+  generic transient error.
+- `30007` — `TOURNAMENT_CANT_CHANGE_REGISTRATION_STATUS`: status
+  transition not allowed (e.g. re-registering after a finished /
+  cancelled tournament). Show a generic error; do not retry.
+- `30008` — `TOURNAMENT_MAX_REGISTRATIONS_REACHED`: the tournament
+  filled up between the lobby fetch and the registration click.
+  Refresh the lobby — the button will hide on the refreshed item.
+- `300010` — insufficient **gems** balance (gems-cost tournament).
+  Same UI handling as `30002` but for the gems currency.
+- `300011` — insufficient **diamonds** balance (diamonds-cost
+  tournament). Same as `300010` but for diamonds. 
+- other non-zero — generic server error. Surface `err_message` if any.
+
+Note: clan-tournament registration can occasionally surface error
+codes from the clan-join domain (e.g. `1011` — joined-after-start)
+via the same response path. These are members of `JoinClanErrorCode`,
+not `TournamentRegistrationError`. Branch on the numeric value.
+
+**Idempotency**: NOT idempotent. A second call on the same instance
+returns `30004` once the first call has succeeded. The SDK does NOT
+enforce an in-flight lock. The consumer MUST guard the call site
+against double-clicks (set a local "registering" flag on click, clear
+it on response).
+
+**Refresh after success (and after failure)**
+The SDK automatically refreshes the tournament lobby cache on every
+response (success OR error) and fires any `onUpdate` callback
+registered via `getTournamentsList({ onUpdate })`. After
+`err_code === 0`, the affected item's `is_user_registered` /
+`registration_status` / `registration_count` reflect the new
+registered state on the refreshed array. Note that
+[getTournamentInstanceInfo](#gettournamentinstanceinfo) is NOT auto-refreshed — if the
+detail screen is open, call it again manually.
+
+The user's balance (points / gems / diamonds) is exposed on the
+user-properties channel and updates independently of this call's
+response — subscribe to user-property updates separately if your UI
+shows the balance.
+
+**Side effects** (consumer-observable on success)
+- Balance debited synchronously by the buy-in amount in the
+  tournament's currency (`registration_cost_points`,
+  `registration_cost_gems`, or `registration_cost_diamonds`). For
+  free tournaments no deduction occurs.
+- Server-side analytics events fire downstream
+  (`tournament_user_registered` for immediate-registration types;
+  `tournament_user_registration_pending` or
+  `tournament_registered_pending_qualification` for
+  manual-approval / qualification-based types).
+- Any operator-configured on-join prizes are distributed (e.g.
+  welcome bonus). These surface via the relevant follow-up channels
+  (e.g. [getBonuses](#getbonuses)).
+
+**UI guidance**: see [UI Guide — `registerInTournament`](../_media/UIGuide_registerInTournament.md).
+
+**Visitor mode**: not supported. Calling from a visitor session
+returns a generic error, not a typed `TournamentRegistrationError`.
+
+#### Example
+
+```ts
+const tournaments = await window._smartico.api.getTournamentsList({
+  onUpdate: (refreshed) => console.log('[smartico] tournament list updated — re-render lobby from this array', refreshed),
+});
+const tournament = tournaments.find(t => t.instance_id === instanceId);
+
+if (!tournament) {
+  console.log('[smartico] tournament not in current lobby — refresh getTournamentsList and retry');
+  return;
+}
+if (!tournament.is_can_register) {
+  console.log('[smartico] tournament not currently registerable — keep CTA disabled');
+  return;
+}
+
+// Clan tournament + user has no clan → resolve clan first.
+if (tournament.is_clan_based) {
+  const userProfile = window._smartico.api.getUserProfile();
+  const userClanId = userProfile?.clan_id;
+  if (userClanId == null) {
+    console.log('[smartico] clan tournament — open the clan-pick modal first; after joinClan resolves, call registerInTournament again');
+    return;
+  }
+}
+
+console.log('[smartico] registration starting — set in-flight flag, show loading dots on the Join button, keep modal open');
+const r = await window._smartico.api.registerInTournament(tournament.instance_id);
+console.log('[smartico] registration response received — clear in-flight flag');
+
+if (r.err_code === 0 || r.err_code === 30004) {
+  console.log('[smartico] registered (or was already) — close any modal, show a success toast; getTournamentsList onUpdate above will fire with the refreshed array');
+} else if (r.err_code === 1010) {
+  console.log('[smartico] clan required — open the clan-pick modal again (this is the server-side safety net for a clan-leave race)');
+} else if (r.err_code === 30002) {
+  console.error('[smartico] insufficient points — show insufficient-balance UI; deficit:', tournament.registration_cost_points);
+} else if (r.err_code === 300010) {
+  console.error('[smartico] insufficient gems — show insufficient-balance UI; deficit:', tournament.registration_cost_gems);
+} else if (r.err_code === 300011) {
+  console.error('[smartico] insufficient diamonds — show insufficient-balance UI; deficit:', tournament.registration_cost_diamonds);
+} else if (r.err_code === 30005) {
+  console.error('[smartico] segment mismatch — prefer the operator-supplied message:', tournament.segment_dont_match_message || r.err_message);
+} else if (r.err_code === 30008) {
+  console.error('[smartico] tournament full — auto-refresh will hide the button on the refreshed lobby item');
+} else {
+  console.error('[smartico] registration failed — show a generic error toast with this message:', r.err_message);
+}
+```
+
 ***