@smartico/public-api 0.0.403 → 0.0.405

package/docs/capabilities/gamePickSubmitSelectionQuiz.md

@@ -0,0 +1,198 @@
+# gamePickSubmitSelectionQuiz — API (GamePickRound)
+
+> Submits all quiz answers for a round in one shot.
+> Import: `import { GamePickRound } from '@smartico/public-api'`
+> Search terms: gamePickSubmitSelectionQuiz, gamepick, GamePickRound, GPRoundStatus, GamePickScoreType, GameRoundOrderType, GamePickRoundPublicMeta, GamePickEvent, SAWGPMarketType, GamePickEventMeta, QuizAnswersValueType, GamePickResolutionType
+
+## Signature
+```ts
+_smartico.api.gamePickSubmitSelectionQuiz(props: GamePickRequestParams & { round: Partial<GamePickRound> }): Promise<GamesApiResponse<GamePickRound>>
+```
+
+## Parameters
+- `props.saw_template_id` — ID of the Quiz game template.
+- `props.round` — Round object with `round_id` + `events[]` carrying the user's answer selections.
+
+## Returns — `Promise<GamesApiResponse<GamePickRound>>`
+Wrapped in `GamesApiResponse`: `errCode` (number — `0` = success), `errMessage?` (string), `data?` — the payload:
+
+`GamePickRound`:
+- `round_id` (number) — Unique round identifier
+- `round_row_id` (number) — Sequential row ID used for ordering rounds
+- `round_name` (string) — Localized display name of the round
+- `round_description` (string) — Localized description of the round
+- `final_screen_cta_button_title` (string) — Label for the CTA button on the final/results screen
+- `final_screen_message` (string) — Message displayed on the final/results screen
+- `final_screen_image_desktop` (string) — URL of the final screen image (desktop)
+- `final_screen_image_mobile` (string) — URL of the final screen image (mobile)
+- `promo_image` (string) — URL of the promotional image for the round
+- `promo_text` (string) — Promotional text displayed with the round
+- `open_date` (number) — Timestamp (ms) when the round opens for participation
+- `last_bet_date` (number) — Timestamp (ms) of the last moment bets are accepted
+- `resolution_date` (number) — Timestamp (ms) when the round is expected to be resolved
+- `score_full_win` (number) — Points awarded for a fully correct prediction
+- `score_part_win` (number) — Points awarded for a partially correct prediction
+- `score_lost` (number) — Points awarded (or deducted) for an incorrect prediction
+- `is_active_now` (boolean) — Whether the round is currently active for participation
+- `is_resolved` (boolean) — Whether the round has been fully resolved and scored
+- `round_status_id` (GPRoundStatus) — Current lifecycle status of the round
+- `events_total` (number) — Total number of events in the round
+- `events_resolved` (number) — Number of events that have been resolved
+- `score_type_id` (GamePickScoreType) — Scoring method used for this round
+- `order_events` (GameRoundOrderType) — How events are ordered for display
+- `board_users_count` (number) — Maximum number of users shown on the leaderboard
+- `hide_users_predictions` (boolean) — Whether other users' predictions are hidden until resolution
+- `public_meta` (GamePickRoundPublicMeta) — Public metadata including translations and display settings from the BackOffice
+  - `round_name` (string) — Localized round name
+  - `round_description` (string) — Localized round description
+  - `promo_image` (string) — URL of the promotional image for the round
+  - `promo_text` (string) — Promotional text displayed with the round
+  - `hide_resolved_round` (boolean) — Whether to hide the round from the UI after it has been resolved
+  - `final_screen_image_desktop` (string) — URL of the final screen image for desktop
+  - `final_screen_image_mobile` (string) — URL of the final screen image for mobile
+  - `final_screen_message` (string) — Message displayed on the final/results screen
+  - `final_screen_cta_button_title` (string) — Label for the CTA button on the final screen
+  - `final_screen_cta_dp` (string) — Deep link triggered by the CTA button on the final screen
+  - `allow_edit_answers` (boolean) — Whether users can edit their answers after initial submission (within betting window)
+  - `_translations` ({
+		[key: string]: {
+			round_name: string;
+			round_description: string;
+			promo_image: string;
+			promo_text: string;
+			final_screen_image_desktop: string;
+			final_screen_image_mobile: string;
+			final_screen_message: string;
+			final_screen_cta_button_title: string;
+		};
+	}) — Per-language overrides for round display content
+- `next_round_open_date` (number) — Timestamp (ms) when the next round opens, if available
+- `show_users_preference` (boolean) — Whether to show aggregated user preference percentages for each outcome
+- `events` (GamePickEvent[]) — List of events (matches/questions) in this round
+  - `gp_event_id` (number) — Unique identifier of the event
+  - `event_resolution_date` (string) — ISO 8601 date-time string when the event was resolved; null until resolved.
+  - `match_date` (string) — ISO 8601 date-time string of the match/event start time.
+  - `market_type_id` (SAWGPMarketType) — Market type defining the prediction format (e.g. two-team score, quiz question, custom)
+  - `event_meta` (GamePickEventMeta) — Event metadata containing team names, images, sport type, and question details
+    - `answers` ({
+		/** Answer identifier value sent on submission */
+		value: string;
+		/** Localized display text of the answer */
+		text: string;
+		/** Per-language overrides for the answer text */
+		_translations: {
+			[key: string]: {
+				text: string;
+			};
+		};
+	}[]) — List of possible answer options for the quiz question
+    - `question_image` (string) — URL of an image associated with the question
+    - `result` (QuizAnswersValueType) — Correct answer value after resolution
+    - `custom_question` (string) — Custom question text displayed to the user
+    - `event_name` (string) — Display name of the event/match
+    - `team1_name` (string) — Name of the first team (home)
+    - `team1_image` (string) — URL of the first team's logo image
+    - `team2_name` (string) — Name of the second team (away)
+    - `team2_image` (string) — URL of the second team's logo image
+    - `team1_result` (number) — Actual result score for team 1 after resolution
+    - `team2_result` (number) — Actual result score for team 2 after resolution
+    - `sport_type_id` (number) — Betradar sport type ID for the event
+    - `is_canceled` (boolean) — Whether the event has been canceled
+    - `auto_resolve_enabled` (boolean) — Whether auto-resolution from live data feed is enabled
+    - `auto_resolve_date` (string) — ISO date string for when auto-resolution is expected
+    - `team1_auto_result` (number) — Auto-resolved score for team 1 from live data feed
+    - `team2_auto_result` (number) — Auto-resolved score for team 2 from live data feed
+    - `auto_result` (string) — Auto-resolved answer value from live data feed (for quiz events)
+    - `_translations` ({
+		[key: string]: {
+			team1_name: string;
+			team2_name: string;
+			event_name: string;
+			custom_question: string;
+		};
+	}) — Per-language overrides for team names, event name, and custom question
+  - `user_placed_bet` (boolean) — Whether the current user has submitted a prediction for this event
+  - `team1_user_selection` (number | { from: number; to: number }) — User's predicted score for team 1 (MatchX only). Can be a number or a range object
+  - `team2_user_selection` (number | { from: number; to: number }) — User's predicted score for team 2 (MatchX only). Can be a number or a range object
+  - `user_selection` (QuizAnswersValueType) — User's selected answer (Quiz only). Value depends on market type (e.g. '1', '2', 'x', 'yes', 'no')
+  - `resolution_type_id` (GamePickResolutionType) — How the user's prediction was scored after resolution
+  - `resolution_score` (number) — Points awarded for this event based on prediction accuracy
+  - `is_open_for_bets` (boolean) — Whether this event is still accepting predictions
+  - `odds_details` ({ odd_value: { [key: string]: number } }) — Betting odds details for the event outcomes
+  - `question_image` (string) — URL of a question-specific image (quiz events)
+- `user_score` (number) — Current user's total score in this round
+- `user_placed_bet` (boolean) — Whether the current user has submitted any predictions in this round
+- `has_open_for_bet_events` (boolean) — Whether there are events still open for betting
+- `has_not_submitted_changes` (boolean) — Whether the user has unsaved changes to their predictions
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode not supported.
+- `saw_template_id` and `props.round.round_id` are mandatory — SDK throws if
+ either is missing.
+- Each event must include `gp_event_id` and `user_selection`. Missing
+ events default to "no change".
+
+
+
+**Idempotency**: identical to `gamePickSubmitSelection` — re-submit
+returns `errCode: 3` and never double-charges the buy-in.
+
+**Side effects**: identical to `gamePickSubmitSelection` — buy-in
+deduction on first submit, participation recorded, score awarded on round
+resolution.
+
+**Visitor mode**: not supported.
+
+**UI guidance**: see [UI Guide — `gamePickSubmitSelectionQuiz`](../../docs/ui/gamepick/UIGuide_gamePickSubmitSelectionQuiz.md).
+
+## Example
+```ts
+const ar = await window._smartico.api.gamePickGetActiveRound({
+    saw_template_id: 1183,
+    round_id:        37974,
+});
+if (ar.errCode !== 0 || !ar.data) {
+    console.error('[smartico] could not fetch round to submit answers — show error');
+    return;
+}
+
+const round = ar.data;
+round.events = round.events.map(e => ({
+    gp_event_id:    e.gp_event_id,
+    user_selection: 'x',
+}));
+
+const r = await window._smartico.api.gamePickSubmitSelectionQuiz({
+    saw_template_id: 1183,
+    round,
+});
+
+if (r.errCode === 0) {
+    console.log('[smartico] quiz answers saved — show confirmation');
+} else if (r.errCode === 3) {
+    console.log('[smartico] nothing changed — silent no-op');
+} else {
+    console.error('[smartico] quiz submit failed:', r.errMessage);
+}
+```
+
+## Errors
+**Error codes** (in `errCode`)
+- `0` — success.
+- `3` (`NoBetsUpdatedOnSubmit`) — no changes, OR every event past
+ `last_bet_date`. Buy-in NOT consumed; current round returned in `data`.
+- `4` — round / event not found.
+- `100002` — template not found.
+- `100000` — auth hash invalid.
+- `100004` — generic server error.
+
+Buy-in failures use the same `SAWSpinErrorCode` pass-through values
+as `gamePickSubmitSelection` — see that method's TSDoc for the
+`40001` / `40003` / `40004` / `40007` / `40009` / `40011` / `40012`
+semantics.
+
+## Related
+- `gamePickSubmitSelection`
+- `SAWSpinErrorCode`
+- `GamesApiResponse`

package/docs/capabilities/getAchCategories.md

@@ -0,0 +1,119 @@
+# getAchCategories — API (TAchCategory)
+
+> Returns the list of active mission/badge categories configured for the current label.
+> Import: `import { TAchCategory } from '@smartico/public-api'`
+> Search terms: getAchCategories, missions, TAchCategory, id, name, order
+
+## Signature
+```ts
+_smartico.api.getAchCategories(): Promise<TAchCategory[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TAchCategory[]>`
+Array of `TAchCategory`. Each item:
+- `id` (number) — Stable numeric ID of the category. Used as the key when joining to `TMissionOrBadge.category_ids: number[]`.
+- `name` (string) — Display name of the category, pre-translated server-side. Never null.
+- `order` (number) — Relative display position (lower = appears first). Default 1 when the operator did not configure an explicit order.
+
+## Behavioral contract
+**What categories are**
+- Operator-defined groupings, configured per-label by the brand operator.
+  Only active categories are returned; inactive/deleted ones are filtered out.
+- Each `TAchCategory` exposes `{ id, name, order }`. `name` is the display label;
+  `order` is the relative position (lower = appears first).
+- The same array covers BOTH missions and badges — categories are not filtered by
+  entity type on the server.
+
+**Localization / translation**
+- `name` is **pre-translated server-side** to the authenticated user's stored language.
+  In visitor mode, the language passed to `_smartico.vapi(lang)` drives the
+  translation. Consumers never need to translate `name` themselves.
+- Fallback if no translation exists for the user's language: the brand's EN value
+  is returned. The field is never null.
+
+**Sort order**
+The server does NOT pre-sort. Sort client-side before rendering:
+`categories.sort((a, b) => a.order - b.order)`.
+
+**How missions/badges join to categories**
+Each `TMissionOrBadge` exposes `category_ids: number[]` (zero-or-more,
+many-to-many). A single mission/badge can belong to multiple categories
+simultaneously, or to none. To render a "category → items" view:
+`missions.filter(m => m.category_ids.includes(cat.id))`.
+
+**Uncategorized items**
+Items with `category_ids: []` are NOT represented by a synthetic "Other" entry.
+If your UI needs one, generate it client-side by checking
+`item.category_ids.length === 0`.
+
+**Empty categories**
+A category may be returned even if zero missions/badges reference it. Filter
+out empty categories on the consumer side if you don't want to render section
+headers for them.
+
+**Refresh cadence / cache**
+- The SDK caches the response for 30 seconds. Subsequent calls within that
+  window return the cached array without a network round-trip.
+- The cache is NOT invalidated by mission/badge push events — operator-driven
+  category changes propagate at the next 30 s cache miss.
+- Cache is fully cleared on login / logout.
+- In **visitor mode** additional server-side caching applies on top of the
+  SDK cache; worst-case staleness for an edited/added category is on the order
+  of a few minutes for anonymous viewers.
+
+**Idempotency**: safe. Read-only metadata fetch. Cache de-duplicates concurrent calls.
+
+**Side effects**: none — pure metadata read.
+
+**UI guidance**: see [UI Guide — `getAchCategories`](../../docs/ui/missions/UIGuide_getAchCategories.md).
+
+## Example
+```ts
+const categories = await window._smartico.api.getAchCategories();
+
+if (categories.length === 0) {
+  console.log('[smartico] no categories configured — render missions/badges as a flat list without section headers');
+} else {
+  const sorted = [...categories].sort((a, b) => a.order - b.order);
+  console.log('[smartico] categories loaded — render one tab/section per entry in this order:', sorted.map(c => c.name));
+
+  // Join to missions: render each category as a section
+  const missions = await window._smartico.api.getMissions();
+  for (const cat of sorted) {
+    const items = missions.filter(m => m.category_ids.includes(cat.id));
+    if (items.length === 0) {
+      console.log('[smartico] category has no missions — skip rendering its section header:', cat.name);
+      continue;
+    }
+    console.log(`[smartico] render section "${cat.name}" with ${items.length} mission(s)`);
+  }
+
+  // Uncategorized items: surface in a caller-provided "Other" bucket if needed
+  const uncategorized = missions.filter(m => m.category_ids.length === 0);
+  if (uncategorized.length > 0) {
+    console.log('[smartico] uncategorized missions exist — render a caller-provided "Other" section; server does NOT return id:-1:', uncategorized.length);
+  }
+}
+
+// Visitor mode — same shape, language driven by vapi(lang) argument
+const visitorCats = await window._smartico.vapi('DE').getAchCategories();
+console.log('[smartico] visitor-mode categories (names translated to DE):', visitorCats);
+```
+
+### 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": 27,
+    "name": "Lucky Badges",
+    "order": 3
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.

package/docs/capabilities/getActivityLog.md

@@ -0,0 +1,108 @@
+# getActivityLog — API (TActivityLog)
+
+> Returns the user's unified balance-change history — every points, gems, and diamonds transaction within the requested time window, ordered newest-first.
+> Import: `import { TActivityLog } from '@smartico/public-api'`
+> Search terms: getActivityLog, user, TActivityLog, UserBalanceType, PointChangeSourceType, onUpdate, subscription
+
+## Signature
+```ts
+_smartico.api.getActivityLog({
+		startTimeSeconds,
+		endTimeSeconds,
+		from,
+		to,
+		onUpdate,
+	}: {
+		/** Window start in epoch seconds. */
+		startTimeSeconds: number;
+		/** Window end in epoch seconds. */
+		endTimeSeconds: number;
+		/** Pagination offset (0-based). */
+		from: number;
+		/** Pagination ceiling (exclusive); server caps `to - from` at 50. */
+		to: number;
+		/** Optional push callback; payload is a fixed 10-min / 50-entry refresh on every wallet change (see Subscription model). */
+		onUpdate?: (data: TActivityLog[]) => void;
+	}): Promise<TActivityLog[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TActivityLog[]>`
+Array of `TActivityLog`. Each item:
+- `create_date` (number) — Date when the change was created (epoch timestamp in seconds)
+- `user_ext_id` (string) — External user ID
+- `crm_brand_id` (number) — CRM brand ID
+- `type` (UserBalanceType) — Type of balance: Points = 0, Gems = 1, Diamonds = 2
+- `amount` (number) — Amount changed (positive or negative)
+- `balance` (number) — Current balance after this change
+- `total_ever` (number) — Total ever collected (only relevant for type points)
+- `source_type_id` (PointChangeSourceType) — Source type ID indicating what triggered this change
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode is not guarded at the SDK level
+  but is not meaningful — activity is per-user.
+
+**Pagination — `from` / `to` are offset + ceiling, not timestamps**
+The SDK derives `offset = from`, `limit = min(to - from, 50)` — the server
+hard-caps a single response at 50 entries. For infinite scroll, advance
+`from` by 50 between calls. Both `startTimeSeconds` and `endTimeSeconds`
+are epoch seconds bounding the window the server scans.
+
+**Subscription model (`onUpdate`)**
+The callback fires when the user's `ach_points_balance`,
+`ach_gems_balance`, or `ach_diamonds_balance` changes (i.e. whenever a
+wallet event lands). The pushed payload is a FIXED re-fetch of the
+**last 10 minutes / first 50 entries** — it does NOT honor the original
+call's `startTimeSeconds` / `endTimeSeconds` / `from` / `to`. Consumers
+maintaining a long historical view must re-call `getActivityLog` with
+their own params after receiving an `onUpdate` notification.
+
+**Refresh**
+- The SDK caches results for 30 seconds.
+- Push triggers fire only on balance changes; transactions that don't
+  alter a balance (theoretical zero-amount entries) won't refresh.
+
+**Visitor mode**: not meaningful (no per-user history available).
+
+**UI guidance**: see [UI Guide — `getActivityLog`](../../docs/ui/user/UIGuide_getActivityLog.md).
+
+## Example
+```ts
+const now = Math.floor(Date.now() / 1000);
+const start = now - 86400 * 30; // 30 days
+
+const log = await window._smartico.api.getActivityLog({
+    startTimeSeconds: start,
+    endTimeSeconds:   now,
+    from: 0,
+    to:   50,
+    onUpdate: (refreshed) => {
+        console.log('[smartico] wallet changed — refreshed payload is last 10 min / 50 entries:', refreshed.length, 'rows');
+        // If the consumer is showing a full 30-day view, re-call getActivityLog with the original params here.
+    },
+});
+
+for (const row of log) {
+    const sign = row.amount >= 0 ? '+' : '';
+    console.log('[smartico] activity row — render with', row.type === 0 ? 'points' : row.type === 1 ? 'gems' : 'diamonds', 'icon, color by sign:', sign + row.amount, 'balance after:', row.balance, 'source:', row.source_type_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
+[
+  null
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `UserBalanceType`
+- `PointChangeSourceType`
+- `TActivityLog`

package/docs/capabilities/getAvatarPrompts.md

@@ -0,0 +1,81 @@
+# getAvatarPrompts — API (TAvatarPrompt)
+
+> Returns the catalog of AI style prompts available for avatar customization.
+> Import: `import { TAvatarPrompt } from '@smartico/public-api'`
+> Search terms: getAvatarPrompts, avatars, TAvatarPrompt, prompt_id, name, icon_url, cost_currency_type_id, cost_value
+
+## Signature
+```ts
+_smartico.api.getAvatarPrompts(): Promise<TAvatarPrompt[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TAvatarPrompt[]>`
+Array of `TAvatarPrompt`. Each item:
+- `prompt_id` (number) — Stable numeric identifier of the prompt.
+- `name` (string) — Display name of the style, e.g. "Cartoon", "Watercolor".
+- `icon_url` (string) — 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, `3` = free. A `cost_value` of `0` is also free.
+- `cost_value` (number) — Cost amount in the currency named by `cost_currency_type_id`. `0` = free.
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode is not supported.
+- No other prerequisite calls. The customization UI typically calls this on demand
+ when the user opens the style picker, not on app boot.
+
+**Cost handling**
+Each prompt declares `cost_currency_type_id` (0 = points, 1 = gems, 2 = diamonds)
+and `cost_value` (amount). The deduction happens server-side inside the
+`avatar-customize` HTTP POST (the AI generation request, which is NOT part of this
+SDK). The client should compare `cost_value` against the live balance from
+`getUserProfile` to disable prompts the user cannot afford, but the server is
+the source of truth and will reject under-funded requests authoritatively.
+
+**Refresh**
+- The SDK caches results for 30 seconds.
+- Not invalidated by `setAvatar` (prompts are catalog metadata, independent
+ of the user's active avatar).
+- No push subscription.
+
+**Visitor mode**: not supported.
+
+**UI guidance**: see [UI Guide — `getAvatarPrompts`](../../docs/ui/avatars/UIGuide_getAvatarPrompts.md).
+
+## Example
+```ts
+const [prompts, profile] = await Promise.all([
+    window._smartico.api.getAvatarPrompts(),
+    window._smartico.api.getUserProfile(),
+]);
+
+for (const p of prompts) {
+    // The consumer reads the matching balance from profile based on
+    // p.cost_currency_type_id (0=points, 1=gems, 2=diamonds).
+    console.log('[smartico] prompt', p.name, '— cost', p.cost_value, 'currency_type', p.cost_currency_type_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
+[
+  {
+    "prompt_id": 1,
+    "name": "Crown",
+    "icon_url": "https://cdn.example/00000000-0000-0000-0000-000000000000/entity-image-1776958855960-1.webp",
+    "cost_currency_type_id": 0,
+    "cost_value": 1
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getUserProfile`
+- `setAvatar`
+- `TAvatarPrompt`

package/docs/capabilities/getAvatarsCustomized.md

@@ -0,0 +1,96 @@
+# getAvatarsCustomized — API (TAvatarCustomized)
+
+> Returns the user's previously generated AI-customized avatar variants.
+> Import: `import { TAvatarCustomized } from '@smartico/public-api'`
+> Search terms: getAvatarsCustomized, avatars, TAvatarCustomized, avatar_real_id, url, dt_created
+
+## Signature
+```ts
+_smartico.api.getAvatarsCustomized(): Promise<TAvatarCustomized[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TAvatarCustomized[]>`
+Array of `TAvatarCustomized`. Each item:
+- `avatar_real_id` (number) — `avatar_real_id` of the base avatar this variant was generated from.
+- `url` (string) — Absolute CDN URL of the AI-generated image. Can be passed as `avatar_url` to `setAvatar()`.
+- `dt_created` (number) — Unix-ms timestamp of when the variant was generated.
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode is not supported.
+- Has meaning only after at least one successful AI customization run (see below).
+ New users get an empty array.
+
+**Where customized avatars come from**
+AI customization is **not** a WebSocket method on this SDK. It is a separate HTTP
+POST to the operator-configured `avatar-customize` endpoint that takes a base avatar
+plus a style prompt from `getAvatarPrompts` and returns a generated CDN URL.
+Once that POST resolves successfully, the new variant is persisted and surfaces in
+the next `getAvatarsCustomized()` call. The variant URL can then be passed to
+`setAvatar` to activate it.
+
+**Relation to `getAvatarsList`**
+AI variants do NOT appear in `getAvatarsList`. Catalog and variants are two
+separate collections — combine them client-side if the UI needs a unified view per
+base avatar.
+
+**Sort order**
+Server does NOT pre-sort. Caller typically sorts by `dt_created` descending to show
+the newest variant first.
+
+**Refresh**
+- The SDK caches results for 30 seconds.
+- `setAvatar` clears this cache on completion.
+- After a successful AI customization POST, the consumer should re-call to surface
+ the new variant — the customization endpoint is outside the SDK so the SDK cannot
+ auto-invalidate.
+- No push subscription.
+
+**Visitor mode**: not supported.
+
+**UI guidance**: see [UI Guide — `getAvatarsCustomized`](../../docs/ui/avatars/UIGuide_getAvatarsCustomized.md).
+
+## Example
+```ts
+const variants = await window._smartico.api.getAvatarsCustomized();
+
+// Group by the base avatar so the UI can show "this base has 3 AI variants".
+const byBase = new Map<number, typeof variants>();
+for (const v of variants) {
+    const list = byBase.get(v.avatar_real_id) ?? [];
+    list.push(v);
+    byBase.set(v.avatar_real_id, list);
+}
+
+// Newest-first within each base.
+for (const list of byBase.values()) {
+    list.sort((a, b) => b.dt_created - a.dt_created);
+}
+
+console.log('[smartico] AI variants by base avatar — render as a carousel under each base');
+```
+
+### 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": 12,
+    "url": "https://cdn.example/avatars/12/00000000-0000-0000-0000-000000000000.png",
+    "dt_created": 1782248067048
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `TAvatarDefinition`
+- `getAvatarsList`
+- `getAvatarPrompts`
+- `setAvatar`
+- `TAvatarCustomized`