@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/getAvatarsList.md

@@ -0,0 +1,101 @@
+# getAvatarsList — API (TAvatarDefinition)
+
+> Returns the avatar catalog available to the current user — every pre-defined avatar configured for the label, with per-user unlock flags (`is_given`, `is_in_use`) applied server-side.
+> Import: `import { TAvatarDefinition } from '@smartico/public-api'`
+> Search terms: getAvatarsList, avatars, getAvatars, TAvatarDefinition, avatar_real_id, is_default, hide_until_achieved, priority, description, url, avatar_url, avatar_source_type_id
+
+## Signature
+```ts
+_smartico.api.getAvatarsList(): Promise<TAvatarDefinition[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TAvatarDefinition[]>`
+Array of `TAvatarDefinition`. Each item:
+- `avatar_real_id` (number) — Stable numeric identifier of the avatar. Primary key passed to `setAvatar()`.
+- `is_default` (boolean) — True when this is the system default avatar for the label.
+- `hide_until_achieved` (boolean) — When true and `is_given === false`, the avatar should be hidden from the user (surprise unlock).
+- `priority` (number) — Display position; lower = earlier in the grid.
+- `description` (string) — Optional description shown alongside the avatar in detail views.
+- `url` (string) — Raw image path as returned by the server (relative or absolute).
+- `avatar_url` (string) — Absolute CDN URL of the avatar image; built from the configured avatar domain + `url`.
+- `avatar_source_type_id` (number) — Source type. `0` = free / always available; non-zero = earned or purchased.
+- `active_from_date` (string) — ISO date string from which the avatar becomes available; undefined when no start window.
+- `active_till_date` (string) — ISO date string until which the avatar is available; undefined when no end window.
+- `is_given` (boolean) — True when the user owns / has unlocked this avatar.
+- `is_in_use` (boolean) — True when this avatar is the user's currently active profile avatar.
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode is not supported.
+- No other prerequisite calls.
+
+**Visibility filter** (consumer-applied)
+Avatars with `hide_until_achieved === true && is_given === false` should be filtered
+out of the grid — they represent surprise unlocks that should remain hidden until
+the user earns them. The default Smartico UI drops these before rendering.
+
+**Lock state** (consumer-applied)
+Lock condition: `!is_given && avatar_source_type_id !== 0`. Free avatars
+(`avatar_source_type_id === 0`) are always selectable; non-free avatars are locked
+until `is_given` flips to true (operator grants via campaign, mission reward, store
+purchase, etc.).
+
+**Sort order**
+Server does NOT pre-sort. Caller must sort by `priority` ascending (lower = first).
+
+**Refresh**
+- The SDK caches results for 30 seconds.
+- `setAvatar` clears this cache on completion; the next call re-fetches.
+- No push subscription — there is no `onUpdate` callback for avatar methods.
+- When `is_given` flips server-side (e.g. the user earns a new avatar), the change
+ surfaces only on the next call after the 30-second cache window expires.
+
+**Visitor mode**: not supported.
+
+**UI guidance**: see [UI Guide — `getAvatarsList`](../../docs/ui/avatars/UIGuide_getAvatarsList.md).
+
+## Example
+```ts
+const avatars = await window._smartico.api.getAvatarsList();
+
+// Apply the standard visibility filter and sort.
+const visible = avatars
+    .filter((a) => !a.hide_until_achieved || a.is_given)
+    .sort((a, b) => a.priority - b.priority);
+
+console.log('[smartico] visible avatars:', visible.length, '— render as a grid');
+
+const active = visible.find((a) => a.is_in_use);
+if (active) {
+    console.log('[smartico] currently in use — overlay a checkmark on this card:', active.avatar_real_id);
+}
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+[
+  {
+    "avatar_real_id": 1,
+    "is_default": false,
+    "hide_until_achieved": false,
+    "priority": 1,
+    "description": "The Pink toast cat, in space, leaving rainbow trails. What else do you need?",
+    "url": "https://cdn.example/83109b74be861920197eb8-cat-space.gif",
+    "avatar_url": "https://cdn.example/83109b74be861920197eb8-cat-space.gif",
+    "avatar_source_type_id": 7,
+    "is_given": false
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getAvatarsCustomized`
+- `setAvatar`
+- `TAvatarDefinition`

package/docs/capabilities/getBadges.md

@@ -0,0 +1,237 @@
+# getBadges — API (TMissionOrBadge)
+
+> Returns all the badges available to the current user.
+> Import: `import { TMissionOrBadge } from '@smartico/public-api'`
+> Search terms: getBadges, missions, getUserBadges, TMissionOrBadge, TMissionOrBadgeTask, AchRelatedGame, TRibbon, AchievementAvailabilityStatus, AchievementClaimPeriodTypeId, BadgesTimeLimitStates, id, name, description, image, is_completed, is_locked, is_requires_optin, is_opted_in
+
+## Signature
+```ts
+_smartico.api.getBadges(): Promise<TMissionOrBadge[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TMissionOrBadge[]>`
+Array of `TMissionOrBadge`. Each item:
+- `id` (number) — ID of the mission or badge
+- `type` ('mission' | 'badge') — Type of entity. Can be 'mission' or 'badge'
+- `name` (string) — Name of the mission or badge, translated to the user language
+- `sub_header` (string) — Sub-header of the mission, translated to the user language
+- `description` (string) — Description of the mission or badge, translated to the user language
+- `reward` (string) — Description of the mission reward if defined
+- `image` (string) — URL of the image of the mission or badge, 256x256px
+- `is_completed` (boolean) — Indicator if the mission is completed or badge is granted
+- `is_locked` (boolean) — Indicator if the mission is locked. Means that it's visible to the user, but he cannot progress in it until it's unlocked. Mission may optionally contain the explanation of what should be done to unlock it in the unlock_mission_description property
+- `unlock_mission_description` (string) — Optional explaination of what should be done to unlock the mission
+- `is_requires_optin` (boolean) — Indicator if the mission requires opt-in. Means that user should explicitly opt-in to the mission in order to start progressing in it
+- `is_opted_in` (boolean) — Indicator if the user opted-in to the mission
+- `time_limit_ms` (number) — The amount of time in milliseconds that user has to complete the mission
+- `active_from_ts` (number) — Holds time from which mission will become available, for the missions that are targeted to be available from specific date/time
+- `active_till_ts` (number) — Holds time till mission will become unavailable, for the missions that are targeted to be available from specific date/time
+- `dt_start` (number) — The date when the mission was started, relevant for the time limited missions, also indicating opt-it date for mission that requires opt-in and unlock date for Locked mission.
+- `progress` (number) — The progress of the mission in percents calculated as the aggregated relative percentage of all tasks
+- `cta_action` (string) — The action that should be performed when user clicks on the mission or badge Can be URL or deep link, e.g. 'dp:deposit'. The most safe to execute CTA is to pass it to _smartico.dp(cta_action); The 'dp' function will handle the CTA and will execute it in the most safe way
+- `cta_text` (string) — The text of the CTA button, e.g. 'Make a deposit'
+- `custom_section_id` (number) — The ID of the custom section where the mission or badge is assigned. Resolve to section metadata via `_smartico.api.getCustomSections()`.
+- `only_in_custom_section` (boolean) — The indicator if the mission or badge is visible only in the custom section and should be hidden from the main overview of missions/badges
+- `custom_data` (any) — The custom data of the mission or badge defined by operator. Can be a JSON object, string or number
+- `tasks` (TMissionOrBadgeTask[]) — The list of tasks of the mission or badge
+  - `id` (number) — ID of the task
+  - `name` (string) — Name of the task, translated to the user language
+  - `is_completed` (boolean) — Indicator if the task is completed
+  - `progress` (number) — The progress of the task in percents
+  - `points_reward` (number) — Reward for completing the task in points
+  - `gems_reward` (number) — Reward for completing the task in gems
+  - `diamonds_reward` (number) — Reward for completing the task in diamonds
+  - `execution_count_expected` (number) — This is the total number of times the user needs to execute to complete task. e.g. he needs to bet 100 times. Here will be 100
+  - `execution_count_actual` (number) — This is the number of times the user has executed 'activity' of the task. e.g. he bet 5 times out of 100. Here will be 5
+- `related_games` (AchRelatedGame[]) — List of casino games (or other types of entities) related to the mission or badge
+  - `ext_game_id` (string) — The ID of the related game
+  - `game_public_meta` ({
+		/** The name of the game */
+		name: string;
+		/** The URL to the game */
+		link: string;
+		/** The URL to the image of the game, 1:1 aspect ratio */
+		image: string;
+		/** The indicator if the game is enabled */
+		enabled: boolean;
+		/** The list of categories of the game */
+		game_categories: string[];
+		/** The name of the game provider */
+		game_provider: string;
+		/** The URL to the mobile game */
+		mobile_spec_link: string;
+		/** The priority of the game */
+		priority?: number;
+	}) — Game public meta information
+- `category_ids` (number[]) — The list of IDs of the categories where the badge item is assigned, information about categories can be retrieved with getAchCategories method
+- `hint_text` (string) — The T&C text for the missions
+- `position` (number) — Priority (or position) of the mission in the UI. Low value indicates higher position in the UI
+- `ribbon` (TRibbon) — The ribbon of the mission/badge item. Can be 'sale', 'hot', 'new', 'vip' or URL to the image in case of custom ribbon, 250x300px
+- `ach_completed_id` (number) — Stable identifier of this specific mission completion. Undefined for badges and for missions that have not yet completed.
+- `requires_prize_claim` (boolean) — Flag from achievement if the mission prize will be given only after user claims it
+- `prize_claimed_date_ts` (number) — The date/timestamp indicating when the prize was claimed by the user
+- `complete_date` (string) — Date-time the mission/badge was completed, as a `"dd/MM/yyyy HH:mm:ss"` string (server local — NOT ISO-8601, so `new Date(complete_date)` will not parse it). Prefer the epoch-ms `complete_date_ts` for date math.
+- `complete_date_ts` (number) — Time of mission/badge being completed, this property shows the epoch time in UTC
+- `completed_today` (boolean) — Flag for mission/badge indicating that mission/badge completed today
+- `completed_this_week` (boolean) — Flag for mission/badge indicating that mission/badge completed this week
+- `completed_this_month` (boolean) — Flag for mission/badge indicating that mission/badge completed this month
+- `custom_section_type_id` (number) — ID of specific Custom Section type
+- `max_completion_count` (number) — Max number of times the user can complete a mission in case if mission type is Recurring upon completion. NULL equals infinite.
+- `completion_count` (number) — Current completion count for Recurring upon completion missions
+- `next_recurrence_date_ts` (number) — The date/timestamp for recurring missions, which indicating the time remaining until the next recurrence of the mission. Note that if a mission has an "Active till" date defined, this field is not relevant after that date.
+- `availability_status` (AchievementAvailabilityStatus) — Availability status of the mission depends on the defined time limits
+- `claim_button_title` (string) — Title for the claim reward button
+- `claim_button_action` (string) — Action for the claim reward button
+- `prize_claim_expiration_date` (number) — The date/timestamp indicating when the mission claim will expire
+- `prize_claim_period_type_id` (AchievementClaimPeriodTypeId) — The type of the prize claim period (Relative or Exact time and date)
+- `badgeTimeLimitState` (BadgesTimeLimitStates) — Badge time limit state for badges with time restrictions
+- `hide_locked_mission` (boolean) — Flag from achievement if the mission should be hidden when it is locked, until it's unlocked
+
+## Behavioral contract
+**Why no `onUpdate` callback?**
+Unlike `getMissions({ onUpdate })`, this method does NOT accept an
+`onUpdate` subscription. Internally the SDK never refreshes the `Badges`
+cache from server pushes: the achievement-related push events
+(mission opt-in / claim / reload) refresh the missions cache, NOT
+the badges cache. The badges cache is flushed only by:
+- its 30-second TTL
+- a full SDK cache wipe at login / logout
+
+**How to refresh the badge list**
+If you need near-live badge state, poll manually after the TTL expires.
+The first call inside the 30 s window returns the cached payload; the
+first call after the TTL triggers a fresh server round-trip. Example:
+```ts
+setInterval(async () => {
+ const badges = await window._smartico.api.getBadges();
+ console.log('[smartico] badge list polled — re-render badge grid from this array', badges);
+}, 30_000);
+```
+Alternatively, re-fetch on a domain event your app already handles
+(e.g. after the user finishes a game round or claims a bonus).
+
+**Differences from missions** (same `TMissionOrBadge` shape, different
+feature)
+The opt-in, claim, recurring-cycle, and unlock-description fields on
+the returned objects are not populated for badges; treat their values
+as undefined / default. Time windows are absolute calendar timestamps
+(`active_from_ts` / `active_till_ts`), not opt-in-relative durations —
+drive availability chips from the SDK-computed `badgeTimeLimitState`
+(enum `BadgesTimeLimitStates`), not `time_limit_ms`. Locking for
+badges is purely time-based: `is_locked` is `true` only when
+`badgeTimeLimitState === BadgesTimeLimitStates.BeforeStartDate` (the
+time window hasn't started yet). The primary navigation field is
+`category_ids` — call `getAchCategories` to resolve category
+metadata and group badges by category.
+
+**Idempotency / Side effects**: fetch-only; safe to call repeatedly.
+The cache layer deduplicates concurrent calls within the TTL window.
+
+**Visitor mode**: not supported. Badges are an authenticated-only
+feature; calling this on the visitor-mode handle (`_smartico.vapi`)
+throws synchronously rather than silently returning an empty list.
+
+**UI guidance**: see [UI Guide — `getBadges`](../../docs/ui/missions/UIGuide_getBadges.md).
+
+## Example
+```ts
+const [badges, categories] = await Promise.all([
+  window._smartico.api.getBadges(),
+  window._smartico.api.getAchCategories(),
+]);
+
+console.log('[smartico] badges fetched — render grouped grid with', badges.length, 'badges across', categories.length, 'categories');
+
+for (const category of categories) {
+  const inCategory = badges.filter(b => b.category_ids?.includes(category.id));
+  const completed = inCategory.filter(b => b.is_completed).length;
+  console.log(`[smartico] render category section "${category.name}" header showing ${completed}/${inCategory.length}`);
+
+  for (const badge of inCategory) {
+    // Use badgeTimeLimitState (not time_limit_ms) for availability chip
+    if (badge.badgeTimeLimitState === 0) { // BadgesTimeLimitStates.BeforeStartDate
+      console.log('[smartico] badge not yet started — render grayscaled card with "Starts on" chip for badge', badge.id);
+    } else if (badge.is_completed) {
+      console.log('[smartico] badge completed — render with completed styling and check-mark for badge', badge.id);
+    } else {
+      console.log('[smartico] badge in progress — render with stage counter (completed_tasks / total) for badge', badge.id);
+    }
+  }
+}
+
+// No onUpdate available — poll if live state matters
+setInterval(async () => {
+  try {
+    const fresh = await window._smartico.api.getBadges();
+    console.log('[smartico] badge poll tick — diff against previous list and re-render any changed badge cards', fresh);
+  } catch (e) {
+    console.error('[smartico] badge poll failed — keep showing last known state, retry on next tick:', e);
+  }
+}, 30_000);
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+[
+  {
+    "id": 40733,
+    "name": "Deep Blue Bet",
+    "description": "Place a bet on Ocean Riches",
+    "image": "https://cdn.example/843b3b60ad20cb6df257c5-puzzle_01.webp",
+    "is_completed": true,
+    "is_locked": false,
+    "is_requires_optin": false,
+    "is_opted_in": false,
+    "time_limit_ms": null,
+    "active_from_ts": null,
+    "active_till_ts": null,
+    "dt_start": null,
+    "progress": 100,
+    "type": "badge",
+    "custom_section_id": 1128,
+    "only_in_custom_section": true,
+    "custom_data": {},
+    "position": 1,
+    "tasks": [
+      {
+        "id": 71250,
+        "name": "Place a bet on Ocean Riches",
+        "points_reward": 0,
+        "gems_reward": null,
+        "diamonds_reward": null,
+        "is_completed": true,
+        "progress": 100,
+        "execution_count_expected": 1,
+        "execution_count_actual": 1
+      }
+    ],
+    "related_games": [],
+    "category_ids": [],
+    "ach_completed_id": 3410338746,
+    "requires_prize_claim": false,
+    "prize_claimed_date_ts": null,
+    "complete_date": "08/06/2026 20:59:17",
+    "complete_date_ts": 1780952357322,
+    "completed_today": false,
+    "completed_this_week": false,
+    "completed_this_month": true,
+    "custom_section_type_id": 14,
+    "availability_status": 0,
+    "hide_locked_mission": true,
+    "prize_claim_expiration_date": null,
+    "prize_claim_period_type_id": null
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getMissions`
+- `BadgesTimeLimitStates`
+- `getAchCategories`

package/docs/capabilities/getBonuses.md

@@ -0,0 +1,159 @@
+# getBonuses — API (TBonus)
+
+> Returns the bonuses awarded to the current user — both pending (player-claim required) and already-redeemed.
+> Import: `import { TBonus } from '@smartico/public-api'`
+> Search terms: getBonuses, bonuses, TBonus, BonusStatus, BonusTemplateMetaMap, BonusMetaMap, onUpdate, subscription, bonus_id, is_redeemable, create_date, redeem_date, label_bonus_template_id, bonus_status_id, label_bonus_template_meta_map, bonus_meta_map
+
+## Signature
+```ts
+_smartico.api.getBonuses({ onUpdate }: { onUpdate?: (data: TBonus[]) => void } = {}): Promise<TBonus[]>
+```
+
+## Parameters
+- `params` — Optional. Omit to fetch without subscribing.
+- `params.onUpdate` — Callback invoked with the full refreshed bonuses list after every `claimBonus` resolves. Each call to `getBonuses` overwrites the prior callback.
+
+## Returns — `Promise<TBonus[]>`
+Array of `TBonus`. Each item:
+- `bonus_id` (number) — Stable ID of the bonus.
+- `is_redeemable` (boolean) — `true` when the bonus is in a player-claim-required state. Gate the Claim button on this; see `claimBonus` TSDoc.
+- `create_date` (string) — Bonus creation timestamp as ISO 8601 UTC string ("YYYY-MM-DDTHH:MM:SS", no timezone suffix).
+- `redeem_date` (string) — Bonus redemption timestamp as ISO 8601 UTC string. Absent until the bonus reaches `BonusStatus.REDEEMED`.
+- `label_bonus_template_id` (number) — ID of the bonus template used to issue this bonus.
+- `bonus_status_id` (BonusStatus) — Lifecycle status; see `BonusStatus`.
+- `label_bonus_template_meta_map` (BonusTemplateMetaMap) — Template-level display metadata (operator-configured, identical across all bonuses from the same template).
+  - `description` (string) — Operator-set description / display text. May include HTML.
+  - `acknowledge` (string) — Operator-set additional message shown to the player at claim time (e.g. wagering terms). May include deep-links.
+  - `image_url` (string) — Bonus icon URL (1:1 aspect ratio recommended).
+  - `redirect_url` (string) — Optional redirect — external HTTP URL (opens in new tab) or internal deep-link (handled by the SDK's deep-link router).
+- `bonus_meta_map` (BonusMetaMap) — Instance-level display metadata (per-issuance; carries the dynamic amount computed at award time).
+  - `uiAmount` (string) — Display-ready amount string (e.g. "€50", "100 free spins").
+
+## Behavioral contract
+**Subscription model (`onUpdate`)**
+The callback receives the FULL refreshed bonuses list (never a
+diff/patch). Each subsequent call to `getBonuses({ onUpdate })`
+REPLACES the prior callback. Pass `onUpdate: undefined` (or omit
+it) to keep the prior callback in place; the callback is never
+auto-cleared.
+
+**Update triggers** — the callback fires after every
+`claimBonus` call resolves on this connection (success OR
+failure). This is the ONLY trigger.
+
+Does NOT fire when: a new bonus is awarded server-side
+(CRM rule, mission completion, store purchase, etc.), a bonus
+expires, or an operator manually issues / cancels a bonus. Those
+changes surface only on the next cache miss (after the 30 s TTL).
+Re-call `getBonuses()` manually if your UI needs near-live state
+for server-driven awards.
+
+**Reading state from the returned bonus**
+Drive UI bucketing from `bonus_status_id` (enum `BonusStatus`):
+
+- `COUPON_ISSUED` (2) — actionable; player must claim. Pair with
+ `is_redeemable === true` to gate the Claim button.
+- `REDEEM_FAILED` (4) — also actionable; the previous claim
+ attempt failed but the bonus is still valid. Surface a retry CTA
+ — the default Smartico UI treats this identically to
+ `COUPON_ISSUED` from the player's perspective.
+- `REDEEMED` (3) — historical; show in a "claimed" tab.
+- `New` (1), `COUPON_ISSUE_FAILED` (5), `EXPIRED` (6) — these
+ should not normally reach the client and are typically filtered
+ out by operator-side widget configuration; if they do appear,
+ they have no player-actionable state.
+
+`is_redeemable` is the authoritative gate for showing the Claim
+button — it's `true` only when the bonus is in a claimable status
+AND the operator's integration uses a coupon model (where the
+player must explicitly trigger delivery). Auto-redeemed bonuses
+arrive already in `REDEEMED` state with `is_redeemable: false`.
+
+**Field hierarchy — display amount**
+Bonuses carry both template-level (`label_bonus_template_meta_map.description`)
+and instance-level (`bonus_meta_map.uiAmount`) display strings.
+Prefer `bonus_meta_map.uiAmount` when present — it's the dynamic
+amount computed at issuance time (e.g. from a dynamic-bonus
+formula). Fall back to `label_bonus_template_meta_map.description`
+(which can include HTML; sanitize before injecting).
+
+**Date format**
+`create_date` and `redeem_date` are ISO 8601 UTC strings WITHOUT
+a timezone suffix (`"YYYY-MM-DDTHH:MM:SS"`). Parse as UTC and
+display in the user's local timezone. `redeem_date` is absent
+until the bonus reaches `REDEEMED` status.
+
+**Cache TTL**: the SDK caches the response for 30 seconds. Cache
+is fully cleared on login / logout.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getBonuses`](../../docs/ui/bonuses/UIGuide_getBonuses.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const bonuses = await window._smartico.api.getBonuses({
+  onUpdate: (refreshed) => {
+    console.log('[smartico] bonuses refreshed (after claimBonus) — re-render the bonuses UI from this array:', refreshed);
+  },
+});
+
+// Bucket into pending vs redeemed tabs. The default Smartico UI groups
+// COUPON_ISSUED + REDEEM_FAILED into the same "Pending" tab.
+const pending = bonuses.filter(b =>
+  b.bonus_status_id === 2 || b.bonus_status_id === 4  // COUPON_ISSUED or REDEEM_FAILED
+);
+const redeemed = bonuses.filter(b => b.bonus_status_id === 3);  // REDEEMED
+
+console.log('[smartico] render bonus tabs: pending=', pending.length, 'redeemed=', redeemed.length);
+
+// Render each pending bonus card; show Claim button only when redeemable.
+for (const b of pending) {
+  const amount = b.bonus_meta_map?.uiAmount || b.label_bonus_template_meta_map?.description;
+  if (b.is_redeemable) {
+    console.log('[smartico] render Claim button for bonus', b.bonus_id, '— amount:', amount);
+  } else {
+    console.log('[smartico] render bonus as informational (no Claim button) — amount:', amount);
+  }
+}
+
+// Server-awarded bonuses (e.g. from a CRM campaign) do NOT push;
+// poll if you need near-live awareness.
+setInterval(async () => {
+  const fresh = await window._smartico.api.getBonuses();
+  const newCount = fresh.filter(b => b.bonus_status_id === 2 || b.bonus_status_id === 4).length;
+  console.log('[smartico] poll tick — pending bonuses now:', newCount);
+}, 30_000);
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+[
+  {
+    "bonus_id": 910171929,
+    "is_redeemable": false,
+    "create_date": "09/06/2026 23:05:03",
+    "redeem_date": "09/06/2026 23:05:03",
+    "label_bonus_template_id": 2152,
+    "bonus_status_id": 3,
+    "label_bonus_template_meta_map": {
+      "name": "",
+      "description": "100 Euro Free Chip",
+      "image_url": "https://cdn.example/4011a701f070093978f2df-Storeitemcopy12.png"
+    },
+    "bonus_meta_map": {
+      "uiAmount": "100 EUR Big Bonus "
+    }
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `BonusStatus`
+- `claimBonus`

package/docs/capabilities/getClanInfo.md

@@ -0,0 +1,164 @@
+# getClanInfo — API (TClanInfo)
+
+> Returns the full detail of a single clan — adds the ranked `members[]` roster and a fresh `cooldown_until` on top of the same fields exposed on a `TClan` list entry.
+> Import: `import { TClanInfo } from '@smartico/public-api'`
+> Search terms: getClanInfo, clans, TClanInfo, Member, Avatar, Numeric, External, clan_id, public_meta, member_count, capacity_limit, entry_fee_currency_type_id, entry_fee_amount, rating_position, rating_score
+
+## Signature
+```ts
+_smartico.api.getClanInfo(clanId: number): Promise<TClanInfo>
+```
+
+## Parameters
+- `clanId` — The clan ID from `TClans.clans[i].clan_id`.
+
+## Returns — `Promise<TClanInfo>`
+`TClanInfo`:
+- `clan_id` (number) — Clan ID.
+- `public_meta` ({ name: string; description: string; image_url: string }) — Translated clan metadata (name, description, image URL).
+- `member_count` (number) — Current number of members in clan.
+- `capacity_limit` (number) — Max number of members allowed in clan.
+- `entry_fee_currency_type_id` (number) — Currency type for `entry_fee_amount`. `0` = points, `1` = gems, `2` = diamonds, `3` = free.
+- `entry_fee_amount` (number) — Entry fee amount in the currency indicated by `entry_fee_currency_type_id`.
+- `rating_position` (number) — Global rank among all active clans in the label, by `rating_score` DESC. `1` = highest-rated.
+- `rating_score` (number) — Clan rating score (higher is better).
+- `cooldown_until` (string | null) — User-level switch-cooldown expiry as ISO 8601 UTC string ("YYYY-MM-DDTHH:MM:SS" with no timezone suffix). `null` when no cooldown. Same semantic as `TClans.cooldown_until` but always fresh (the list version may be up to 30 s stale).
+- `members` ({
+		/** Member's internal user ID. */
+		user_id: number;
+		/** Member's display username. */
+		public_username: string;
+		/** Avatar identifier; resolve via `avatar_url` below or rebuild
+		 * from `avatar_id` + brand avatar domain. */
+		avatar_id: string;
+		/** Numeric avatar ID (alternative identifier). */
+		avatar_real_id: number;
+		/** Pre-resolved CDN URL for the avatar. */
+		avatar_url?: string;
+		/** Member's rank within this clan; `1` = top contributor. */
+		position: number;
+		/** Member's contribution to the clan rating score. */
+		contribution_score: number;
+		/** `true` when this row is the current authenticated user. */
+		is_me?: boolean;
+		/** External user identifier (operator-provided alias);
+		 * preferred over `public_username` on some surfaces. */
+		clean_ext_user_id?: string;
+	}[]) — Members of this clan, server-ordered by `contribution_score` DESC (i.e. `position` ASC).
+
+## Behavioral contract
+**Preconditions**
+Pass a valid `clanId` (typically read from
+`TClans.clans[i].clan_id` returned by `getClans`). The
+method works standalone — `getClans()` is not required first —
+but is the only stable source of valid IDs.
+
+**Refresh model**
+- **No subscription.** One-shot promise.
+- **No client cache.** Every call sends a network request.
+- **No push event** refreshes the detail. Member-join, kick, or
+ contribution-score changes require a fresh `getClanInfo` call.
+
+**Returned shape — beyond `TClan`**
+`TClanInfo` adds two things on top of the same identity / capacity
+/ fee / rating fields you'd see on a `TClan` list entry:
+1. A ranked `members[]` array — each entry carries `user_id`,
+ `public_username`, `avatar_id` / `avatar_real_id`, the resolved
+ `avatar_url`, the member's `position` (rank within this clan),
+ `contribution_score`, the `is_me` flag identifying the current
+ user's row, and the optional `clean_ext_user_id`. The server
+ orders members by score DESC (i.e. `position` ASC); no
+ client-side re-sort is required.
+2. A fresh `cooldown_until` on the clan info itself. This is the
+ SAME user-level cooldown as `TClans.cooldown_until` (the
+ cooldown is global to the user, not per clan) — but `getClans`
+ returns a value cached for up to 30 s while `getClanInfo`
+ always returns the current value. If the list-cached cooldown
+ has just expired, this detail call will reflect it first.
+
+**Username display**: in the default Smartico UI, member rows use
+`public_username`. Some surfaces (e.g. the tournament clan
+drill-down) prefer `clean_ext_user_id` as the primary display
+with `public_username` as fallback — pick the convention that
+matches your product's identity model.
+
+**Idempotency**: safe. Read-only.
+
+**Side effects**: none — pure metadata read.
+
+**UI guidance**: see [UI Guide — `getClanInfo`](../../docs/ui/clans/UIGuide_getClanInfo.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const result = await window._smartico.api.getClans();
+const clan = result.clans[0];
+
+console.log('[smartico] loading detail for clan', clan.clan_id);
+const detail = await window._smartico.api.getClanInfo(clan.clan_id);
+
+console.log('[smartico] render detail with', detail.members.length, 'members');
+
+// Find current user's row to power a sticky "me" footer.
+const meRow = detail.members.find(m => m.is_me);
+if (meRow) {
+  console.log('[smartico] current user rank in this clan:', meRow.position,
+    'contribution:', meRow.contribution_score, '— render sticky my-member footer');
+}
+
+// Resolve Join CTA state using the detail's cooldown (always fresh).
+const isMyClan = detail.clan_id === result.user_clan_id;
+const inCooldown = detail.cooldown_until != null;
+const isFull = detail.member_count >= detail.capacity_limit;
+if (isMyClan) {
+  console.log('[smartico] this is the user\'s clan — render disabled "Your clan" button');
+} else if (inCooldown) {
+  const ends = new Date(detail.cooldown_until + 'Z');
+  console.log('[smartico] user is in clan-switch cooldown until', ends.toLocaleString(),
+    '— render disabled cooldown button');
+} else if (isFull) {
+  console.log('[smartico] clan is full — render disabled "Clan is full" button');
+} else {
+  console.log('[smartico] joinable — render enabled Join button');
+}
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+{
+  "clan_id": 6,
+  "public_meta": {
+    "name": "Joker Clan",
+    "description": "Join the clan if you're a wild card and are completely out of control! Or if you just hate Bruce Wayne very much.\n\nPlay in the tournaments, grab that cash an…",
+    "image_url": "https://cdn.example/00000000-0000-0000-0000-000000000000/entity-image-1780057181857-1.png"
+  },
+  "member_count": 885,
+  "capacity_limit": 1000,
+  "entry_fee_currency_type_id": 0,
+  "entry_fee_amount": 100,
+  "rating_position": 1,
+  "rating_score": 90,
+  "cooldown_until": null,
+  "members": [
+    {
+      "user_id": 183751733,
+      "public_username": "Daniel",
+      "avatar_id": "183751733",
+      "avatar_real_id": null,
+      "avatar_url": "https://cdn.example/avatar/183751733",
+      "position": 1,
+      "contribution_score": 456786,
+      "is_me": false,
+      "clean_ext_user_id": "0"
+    }
+  ]
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getClans`