@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/getClanTournamentPlayers.md

@@ -0,0 +1,112 @@
+# getClanTournamentPlayers — API (TClanTournamentPlayers)
+
+> Returns the ranked players of a specific clan within a clan-based tournament instance.
+> Import: `import { TClanTournamentPlayers } from '@smartico/public-api'`
+> Search terms: getClanTournamentPlayers, tournaments, TClanTournamentPlayers
+
+## Signature
+```ts
+_smartico.api.getClanTournamentPlayers(tournamentInstanceId: number, clanId: number): Promise<TClanTournamentPlayers>
+```
+
+## Parameters
+- `tournamentInstanceId` — The tournament `instance_id` from a clan-based `TTournament`.
+- `clanId` — The clan ID from `TTournamentDetailed.clan_leaderboard[].clan_id`.
+
+## Returns — `Promise<TClanTournamentPlayers>`
+`TClanTournamentPlayers`:
+- `clan_id` (number) — Clan ID
+- `clan_public_meta` ({ name: string; image_url: string }) — Clan display metadata
+- `players` ({
+		user_id: number;
+		public_username: string;
+		avatar_id: string;
+		avatar_real_id: number;
+		avatar_url?: string;
+		position: number;
+		scores: number;
+		is_me: boolean;
+		clean_ext_user_id: string;
+	}[]) — Top players of this clan ranked by score DESC
+
+## Behavioral contract
+**Preconditions**
+Pass a valid `tournamentInstanceId` (read from `TTournament.instance_id`
+returned by `getTournamentsList`) and a `clanId` (read from
+`TTournamentDetailed.clan_leaderboard[].clan_id` returned by
+`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`) 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`](../../docs/ui/tournaments/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);
+  }
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getTournamentsList`
+- `getTournamentInstanceInfo`

package/docs/capabilities/getClans.md

@@ -0,0 +1,168 @@
+# getClans — API (TClans)
+
+> Returns the active clans visible to the current user along with the user's own membership state (`user_clan_id`, `cooldown_until`, `join_date`).
+> Import: `import { TClans } from '@smartico/public-api'`
+> Search terms: getClans, clans, TClans, TClan, onUpdate, subscription, user_clan_id, cooldown_until, join_date
+
+## Signature
+```ts
+_smartico.api.getClans({ onUpdate }: { onUpdate?: (data: TClans) => void } = {}): Promise<TClans>
+```
+
+## Parameters
+- `params` — Optional. Omit to fetch without subscribing.
+- `params.onUpdate` — Callback invoked with the full refreshed `TClans` payload whenever the 30 s cache expires and a subsequent fetch lands. Each call to `getClans` overwrites the prior callback.
+
+## Returns — `Promise<TClans>`
+`TClans`:
+- `clans` (TClan[]) — List of active clans available to the user
+  - `clan_id` (number) — Clan ID
+  - `public_meta` ({
+		name: string;
+		description: string;
+		image_url: string;
+	}) — Translated clan metadata
+  - `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 (no fee).
+  - `entry_fee_amount` (number) — Entry fee amount in the currency indicated by `entry_fee_currency_type_id`. `0` (or `entry_fee_currency_type_id === 3`) means the clan is free to join.
+  - `rating_position` (number) — Global rank among all active clans in the label, by `rating_score` DESC. `1` = highest-rated. May skip positions when some clans are hidden by per-user visibility (e.g. user sees positions 1, 3, 7).
+  - `rating_score` (number) — Clan rating score (higher is better).
+- `user_clan_id` (number | null) — The clan ID the current user belongs to; null if clanless
+- `cooldown_until` (string | null) — Switch-cooldown expiry as ISO 8601 UTC string ("YYYY-MM-DDTHH:MM:SS" with no timezone suffix; interpret as UTC). `null` when no cooldown. User-level: while set, the user cannot join any clan.
+- `join_date` (number | null) — Epoch ms when the current user joined their clan; null if clanless
+
+## Behavioral contract
+**Subscription model (`onUpdate`)**
+The callback receives the FULL refreshed `TClans` payload (never a
+diff/patch). Each subsequent call to `getClans({ 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** — note that, unlike most other subscription
+methods in the SDK, this callback is **poll-driven only**. There
+is NO server push that refreshes the clans list. The callback
+fires when:
+
+1. The 30-second cache TTL expires and a subsequent `getClans()`
+ call (from the consumer) triggers a fresh fetch.
+
+Consequence: clan-membership changes (other users joining your
+clan, an operator-driven kick, a clan being archived) surface
+only on the next consumer-driven fetch. If your UI needs
+near-live state, poll `getClans()` on an interval; or re-call
+after a `joinClan` resolves to pick up the new
+`user_clan_id` immediately.
+
+**Reading state from the returned payload**
+Drive list rendering from `clans[]` (already sorted). Identify
+the user's own clan via `clan.clan_id === user_clan_id`
+(`null` for clanless users). Detect an active switch-cooldown
+with `cooldown_until !== null` — when set, the user cannot join
+any clan until the cooldown expires, even clans they could
+normally join. The cooldown is **user-level**, not per-clan.
+
+`cooldown_until` is an ISO 8601 UTC datetime string with no
+timezone suffix (`"YYYY-MM-DDTHH:MM:SS"`). Parse as UTC:
+`new Date(cooldown_until + 'Z')` or `moment.utc(cooldown_until)`.
+Display in the user's local time. The default cooldown period
+is configured per label by the operator (typically 7 days).
+
+`rating_position` is a global rank computed server-side across
+all active clans in the label (1 = highest-rated). Because some
+clans may be hidden by per-user segment visibility, positions
+the user sees may skip (e.g. 1, 3, 7) — don't assume the array
+spans a contiguous range.
+
+The `entry_fee_currency_type_id` enum on each clan uses values
+`0` = points, `1` = gems, `2` = diamonds, `3` = free. Compare
+`entry_fee_amount` against the user's matching balance (from
+`getUserProfile`) to drive Join button affordability.
+
+**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 payload without a
+network round-trip.
+
+**Side effects**: none — pure metadata read.
+
+**UI guidance**: see [UI Guide — `getClans`](../../docs/ui/clans/UIGuide_getClans.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const result = await window._smartico.api.getClans({
+  onUpdate: (refreshed) => {
+    console.log('[smartico] clans payload refreshed (poll-driven; ~30 s cadence) — re-render the clan list from this payload:', refreshed);
+  },
+});
+
+console.log('[smartico] user is', result.user_clan_id == null ? 'clanless' : 'in clan ' + result.user_clan_id);
+
+// Cooldown handling — affects ALL clans, not a specific one.
+if (result.cooldown_until) {
+  const cooldownEndsUtc = new Date(result.cooldown_until + 'Z');
+  console.log('[smartico] switch-cooldown active — disable all Join buttons until', cooldownEndsUtc.toLocaleString(),
+    '(local). Render the cooldown end on the disabled button label.');
+}
+
+// Render clans — already sorted by rating_position ASC.
+for (const clan of result.clans) {
+  const isMine = clan.clan_id === result.user_clan_id;
+  const isFull = clan.member_count >= clan.capacity_limit;
+
+  if (isMine) {
+    console.log('[smartico] highlight clan', clan.clan_id, 'as "Your clan"; CTA label "Your clan", no-op');
+  } else if (result.cooldown_until) {
+    console.log('[smartico] clan', clan.clan_id, '— Join blocked by user cooldown; show disabled button with cooldown end date');
+  } else if (isFull) {
+    console.log('[smartico] clan', clan.clan_id, '— Clan full; show disabled "Clan is full" button');
+  } else {
+    const label = clan.entry_fee_amount === 0 || clan.entry_fee_currency_type_id === 3
+      ? 'Join free'
+      : `Join (${clan.entry_fee_amount} ${['Points','Gems','Diamonds'][clan.entry_fee_currency_type_id]})`;
+    console.log('[smartico] clan', clan.clan_id, '— render enabled Join button labelled', label);
+  }
+}
+
+// After a successful joinClan(), re-call getClans manually — no push refresh.
+// const r = await window._smartico.api.joinClan(targetClanId);
+// if (r.errCode === 0) await window._smartico.api.getClans();
+```
+
+### 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
+{
+  "clans": [
+    {
+      "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
+    }
+  ],
+  "user_clan_id": null,
+  "cooldown_until": null,
+  "join_date": null
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `joinClan`
+- `getUserProfile`

package/docs/capabilities/getCurrentLevel.md

@@ -0,0 +1,123 @@
+# getCurrentLevel — API (TLevelCurrent)
+
+> Returns the user's current level — every `TLevel` field plus a computed `progress` percentage toward the next level.
+> Import: `import { TLevelCurrent } from '@smartico/public-api'`
+> Search terms: getCurrentLevel, user, getUserLevel, TLevelCurrent, id, name, description, image, required_points, visibility_points, required_level_counter_1, required_level_counter_2
+
+## Signature
+```ts
+_smartico.api.getCurrentLevel(): Promise<TLevelCurrent>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TLevelCurrent>`
+`TLevelCurrent`:
+- `id` (number) — Stable ID of the level.
+- `name` (string) — Display name of the level, pre-translated to the user's language.
+- `description` (string) — Display description of the level, pre-translated to the user's language.
+- `image` (string) — URL of the level image (256x256 px source).
+- `required_points` (number) — Total `ach_points_ever` required to reach this level.
+- `visibility_points` (number) — Visibility threshold — clients hide the level from the user until `ach_points_ever >= visibility_points`. `null` means always visible.
+- `required_level_counter_1` (number) — Required value of the first level counter for sliding-window leveling. `null` on points-only labels. See `UserLevelExtraCountersT`.
+- `required_level_counter_2` (number) — Required value of the second level counter for sliding-window leveling. `null` on points-only labels.
+- `custom_data` (string) — Operator-defined custom data. The SDK auto-parses JSON-looking strings, so at runtime this is `any` despite the `string` type.
+- `ordinal_position` (number) — 1-based position in the ladder (matches the order of the returned array, which is sorted by `required_points` ASC).
+- `progress` (number) — Progress to the next level as a 0–100 integer percentage. `100` at the highest level.
+
+## Behavioral contract
+**How `progress` is computed**
+The SDK derives `progress` as the *delta-from-current-level-floor*:
+`(ach_points_ever − current.required_points) / (next.required_points
+− current.required_points) × 100`, clamped to `[0, 100]`. At the
+highest level (no next level), `progress` is `100`. Reading the
+source values directly from `getUserProfile`'s
+`ach_points_ever` and `getLevels` would also work, but
+`progress` saves the math.
+
+**Cache TTL & freshness**
+The response is cached for 30 seconds, but the SDK automatically
+drops that cache whenever a user-properties update arrives — the
+same live channel that backs `getUserProfile`. The practical
+effect depends on the label's leveling logic:
+- **Points-based or operator-manual leveling**: a points or level
+ change flows through the user-properties channel, so the cache is
+ busted at that moment and the next `getCurrentLevel()` call
+ returns up-to-date data without waiting out the TTL.
+- **Counter-based leveling** (level driven by sliding-window
+ counters such as deposit or wagering totals over a recent window —
+ see `getUserLevelExtraCounters`): ordinary progress changes
+ are recomputed by a periodic server job and do NOT emit a
+ user-properties update, so they become visible on this method only
+ after the 30 s TTL expires (or after `_smartico.api.clearCaches()`).
+
+Avoid calling `clearCaches()` on the points/manual path — it's
+unnecessary there (the cache is already refreshed on the property
+update) and forces a slower extra round-trip.
+
+**Leveling logic**
+The semantics of how a user advances depends on the label's
+leveling logic (configured per brand): points-only (the default),
+sliding-window with extra counters (uses
+`getUserLevelExtraCounters`), or fully-manual operator
+assignment. The `progress` percentage on this method assumes the
+points-only model — it's not meaningful for manual-only labels
+where level changes are operator-driven rather than points-driven.
+
+**Idempotency**: safe. Read-only. Repeated calls within the cache
+window return a deep-cloned cached value without a network
+round-trip.
+
+**Side effects**: none — pure read.
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const level = await window._smartico.api.getCurrentLevel();
+console.log('[smartico] render level badge — name:', level.name,
+  'progress:', Math.round(level.progress), '%');
+
+// Detect level-up via getUserProfile's push channel. No clearCaches()
+// needed — the SDK already drops the level cache on this update.
+window._smartico.on('props_change', async (changed) => {
+  if ('ach_level_current_id' in changed) {
+    const fresh = await window._smartico.api.getCurrentLevel();
+    console.log('[smartico] user levelled up — animate badge to new level:', fresh.name);
+  }
+});
+```
+
+### 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": 698,
+  "name": "Silver",
+  "description": "Now you’re playing! Enjoy exclusive missions and exciting rewards.",
+  "image": "https://cdn.example/665b45d5a01e2191288091-3silver.png",
+  "required_points": 500,
+  "visibility_points": 0,
+  "required_level_counter_1": null,
+  "required_level_counter_2": null,
+  "custom_data": {
+    "reward": "1000 EUR + 300 Free Spins",
+    "image_inactive": "https://cdn.example/bdf58fecfda5a1b9627f8f-LevelLevel3Enabledfalse.png",
+    "image_active": "https://cdn.example/90a40da1c5e201f8fa1d3c-LevelLevel3Enabledtrue.png",
+    "rakeback": 5,
+    "has_vip_club": true,
+    "cashback": 2
+  },
+  "ordinal_position": 3,
+  "progress": 38
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getUserProfile`
+- `getLevels`
+- `getUserLevelExtraCounters`

package/docs/capabilities/getCustomSections.md

@@ -0,0 +1,96 @@
+# getCustomSections — API (TUICustomSection)
+
+> Returns the operator-configured "custom sections" the current user is eligible to see.
+> Import: `import { TUICustomSection } from '@smartico/public-api'`
+> Search terms: getCustomSections, general, TUICustomSection, AchCustomSectionType, AchCustomLayoutTheme, AchMissionsTabsOptions, AchOverviewMissionsFilter, LiquidEntityData, id, body, menu_img, menu_name, section_type_id, liquid_entity_data, liquid_template
+
+## Signature
+```ts
+_smartico.api.getCustomSections(): Promise<TUICustomSection[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TUICustomSection[]>`
+Array of `TUICustomSection`. Each item:
+- `id` (number) — Stable numeric ID of the section.
+- `body` (string) — Raw HTML body for `HTML_PAGE` sections; Liquid template body for `LEVELS` (Liquid) sections.
+- `menu_img` (string) — CDN URL of the section's nav icon, 64x64 px square.
+- `menu_name` (string) — Display name shown next to the nav icon. Pre-translated server-side.
+- `custom_skin_images` (string) — JSON-serialized list of skin image overrides for themed sections (e.g. `MISSION_CUSTOM_LAYOUT`).
+- `section_type_id` (AchCustomSectionType) — Dispatch key — see `AchCustomSectionType`.
+- `theme` (AchCustomLayoutTheme) — Themed-layout name for `MISSION_CUSTOM_LAYOUT` sections; see `AchCustomLayoutTheme`.
+- `generic_custom_css` (string) — Custom CSS for themed layouts.
+- `mission_tabs_options` (AchMissionsTabsOptions) — Which tabs to render for `MISSIONS_CATEGORY` sections; see `AchMissionsTabsOptions`.
+- `overview_missions_filter` (AchOverviewMissionsFilter) — Mission-filter rule for the Overview tab; see `AchOverviewMissionsFilter`.
+- `overview_missions_count` (number) — Maximum number of missions shown in the Overview tab.
+- `url_or_dp` (string) — Click target for `REDIRECT_LINK` sections — either a Smartico DP string (`dp:…`) or an external URL.
+- `liquid_entity_data` (LiquidEntityData[]) — Data-context selectors for Liquid templates; see `LiquidEntityData`.
+- `ach_tournament_id` (number) — Tournament ID for a single-tournament Liquid template (`LiquidEntityData.Tournament`).
+- `show_raw_data` (boolean) — Operator debug flag — when `true`, Liquid renders raw context data instead of the templated HTML.
+- `liquid_template` (number) — Liquid template ID resolved server-side; the rendered body is delivered in `body`.
+- `ach_category_ids` (number[]) — Category IDs the section filters badges by — correlate with `getAchCategories()`.
+- `shop_category_ids` (number[]) — Category IDs the section filters store items by — correlate with `getStoreCategories()`.
+- `raffle_id` (number) — Raffle ID for `RAFFLE` sections (and `LiquidEntityData.SingleRaffle` Liquid templates).
+
+## Behavioral contract
+**Preconditions**
+- No prerequisite calls. Typically fetched once at app boot to build the
+  navigation skeleton.
+
+**Server-side eligibility filtering**
+Sections are filtered server-side by the user's segments / level / brand and
+the section's `active_from_date` / `active_till_date` window. Sections the
+user is ineligible for are omitted from the response entirely — there is no
+"locked" state to render.
+
+**Ordering**
+Response is server-ordered. Render in the order received; do NOT re-sort
+client-side (the operator's order is the intended nav order).
+
+**Refresh**
+- The SDK caches results for 30 seconds.
+- No push subscription. Re-call after a segment / level change might
+  make new sections eligible, or just rely on the 30 s cache turnover.
+
+**Visitor mode**: supported.
+
+**UI guidance**: see [UI Guide — `getCustomSections`](../../docs/ui/general/UIGuide_getCustomSections.md).
+
+## Example
+```ts
+const sections = await window._smartico.api.getCustomSections();
+
+for (const s of sections) {
+    console.log('[smartico] nav entry', s.menu_name, 'type', s.section_type_id, '→ mount the matching page component');
+    // Render s.menu_img (64x64) as the nav icon and s.menu_name as the label.
+    // For section_type_id === AchCustomSectionType.REDIRECT_LINK, do NOT mount a page —
+    // resolve s.url_or_dp on click (DP string or external URL).
+}
+```
+
+### 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": 625,
+    "body": "<!-- Google Font -->\n<link href=\"https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,100..900;1,100..900&display=swap\" rel=\"stylesheet\">\n\n<style…",
+    "menu_img": "https://cdn.example/9f1d1ae8915eef1f5db75c-Storeitemcopy21ice.png",
+    "menu_name": "Custom overview",
+    "section_type_id": 4,
+    "liquid_entity_data": [
+      1
+    ],
+    "liquid_template": 1
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `AchCustomSectionType`
+- `TUICustomSection`

package/docs/capabilities/getInboxMessageBody.md

@@ -0,0 +1,87 @@
+# getInboxMessageBody — API (TInboxMessageBody)
+
+> Returns the rich body of a single inbox message — title, preview text, icon, click action, optional rich HTML body, and optional buttons.
+> Import: `import { TInboxMessageBody } from '@smartico/public-api'`
+> Search terms: getInboxMessageBody, inbox, TInboxMessageBody, Button, action, icon, title, preview_body, custom_data
+
+## Signature
+```ts
+_smartico.api.getInboxMessageBody(messageGuid: string): Promise<TInboxMessageBody>
+```
+
+## Parameters
+- `messageGuid` — The `message_guid` from a `TInboxMessage` returned by `getInboxMessages`.
+
+## Returns — `Promise<TInboxMessageBody>`
+`TInboxMessageBody`:
+- `title` (string) — Display title.
+- `preview_body` (string) — Short preview text (typically rendered alongside the title in list items).
+- `icon` (string) — Message icon URL (128×128 px recommended).
+- `action` (string) — Click-action — either a deep-link (e.g. `'dp:deposit'`) or a plain URL. The literal `'dp:inbox'` indicates the message has a rich `html_body`; for any other value `html_body` and `buttons` are absent. Pass to `_smartico.dp(action)` for safe execution.
+- `html_body` (string) — Rich HTML body. Populated only when `action === 'dp:inbox'`.
+- `buttons` ({
+		/** Button click-action (deep-link or URL). */
+		action: string;
+		/** Button label. */
+		text: string;
+	}[]) — Up to 2 additional action buttons. Populated only when `action === 'dp:inbox'`.
+- `custom_data` (string) — Operator-defined custom data. The SDK auto-parses JSON-looking strings, so at runtime this is `any` despite the `string` type.
+
+## Behavioral contract
+**Rich vs simple messages**
+The shape of the returned body branches on the `action` field:
+- When `action === 'dp:inbox'`, the message has a rich HTML body
+  (`html_body`) and may have up to 2 action `buttons`. Use these
+  for a full-detail rendering.
+- For any other `action` (deep-link like `'dp:deposit'` or a URL),
+  the message is a simple notification — `html_body` and
+  `buttons` will be `undefined` regardless of what's in the
+  underlying CDN payload. Render `title` + `preview_body` + a
+  single CTA driving the `action`.
+
+**The `action` field**
+For both shapes, `action` carries either a deep-link
+(`'dp:gf_missions'`) or a plain URL. Pass it to `_smartico.dp()`
+for safe execution — that helper handles URL vs deep-link
+routing.
+
+**Idempotency / Side effects**: safe. Read-only HTTP fetch.
+
+**UI guidance**: see [UI Guide — `getInboxMessageBody`](../../docs/ui/inbox/UIGuide_getInboxMessageBody.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const body = await window._smartico.api.getInboxMessageBody(messageGuid);
+
+console.log('[smartico] render message — title:', body.title,
+  '— preview:', body.preview_body,
+  '— icon:', body.icon);
+
+if (body.action === 'dp:inbox' && body.html_body) {
+  console.log('[smartico] rich message — render the html_body in a sandboxed iframe; render up to 2 action buttons:',
+    body.buttons?.length ?? 0);
+} else {
+  console.log('[smartico] simple message — show preview_body + single CTA wired to:', body.action,
+    '— execute via _smartico.dp(body.action)');
+}
+```
+
+### 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
+{
+  "action": "dp:close",
+  "icon": "https://cdn.example/d0f46ded3f7c9439fa0239-home-gems.webp",
+  "title": "Congratulations!",
+  "preview_body": "You have received 10 Gems to your balance!",
+  "custom_data": {}
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getInboxMessages`