@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/getLevels.md

@@ -0,0 +1,118 @@
+# getLevels — API (TLevel)
+
+> Returns the full level ladder configured for the current label — one `TLevel` per active level, server-sorted by `required_points` ASC (lowest first; `ordinal_position` is a 1-based index into the returned array).
+> Import: `import { TLevel } from '@smartico/public-api'`
+> Search terms: getLevels, user, getUserLevels, TLevel, id, name, description, image, required_points, visibility_points, required_level_counter_1, required_level_counter_2
+
+## Signature
+```ts
+_smartico.api.getLevels(): Promise<TLevel[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TLevel[]>`
+Array of `TLevel`. Each item:
+- `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).
+
+## Behavioral contract
+**Server-side filtering**
+The server returns ALL active levels for the label. There is NO
+per-user filtering on visibility, level-status, or anything else —
+the response is identical across users of the same label. Apply
+`visibility_points` filtering client-side if you want to hide
+not-yet-reached levels (compare against
+`getUserProfile().ach_points_ever` and exclude levels where
+`visibility_points > ach_points_ever`).
+
+**Sort order**
+The returned array is already sorted by `required_points` ASC, and
+`ordinal_position` is a 1-based index into that same sort order —
+client-side re-sorting is not required for the default rendering.
+If your label uses sliding-window leveling logic
+(see `getUserLevelExtraCounters`) and you want to sort by
+a multi-criteria key (`required_points`, then
+`required_level_counter_1`, then `required_level_counter_2`), do
+that client-side.
+
+**Cache TTL**: the SDK caches the response for 30 seconds. Cache
+is fully cleared on login / logout. Operator-driven level edits
+surface on the next cache miss.
+
+**Idempotency / Side effects**: safe. Read-only metadata. Calls
+within the cache window de-duplicate to the same cached array.
+
+**UI guidance**: see [UI Guide — `getLevels`](../../docs/ui/user/UIGuide_getLevels.md).
+
+**Visitor mode**: supported. Use `_smartico.vapi(lang).getLevels()`
+to fetch the ladder for anonymous viewers; the level configuration
+is label-scoped static data so the response is meaningful even
+without an authenticated user. Per-user fields (the implicit
+"current level" via `getCurrentLevel`, or the user's progress)
+are not available in visitor mode.
+
+## Example
+```ts
+const [levels, profile] = await Promise.all([
+  window._smartico.api.getLevels(),
+  Promise.resolve(window._smartico.api.getUserProfile()),
+]);
+
+// Resolve the user's current level by ID.
+const current = levels.find(l => l.id === profile.ach_level_current_id);
+console.log('[smartico] render header badge — current level:', current?.name,
+  '(position', current?.ordinal_position, 'of', levels.length, ')');
+
+// Filter to levels the user has unlocked enough to see.
+const visible = levels.filter(l =>
+  l.visibility_points == null || l.visibility_points <= profile.ach_points_ever
+);
+console.log('[smartico] render the level map with', visible.length, 'visible tiles');
+
+// Visitor-mode equivalent: returns the same ladder; no per-user state.
+// const visitorLevels = await window._smartico.vapi('EN').getLevels();
+```
+
+### 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": 696,
+    "name": "Stone",
+    "description": "Your journey begins here! Step into the game and start climbing the ranks.",
+    "image": "https://cdn.example/1a4199871dc30acf09374a-1stone.png",
+    "required_points": 0,
+    "visibility_points": 0,
+    "required_level_counter_1": 0,
+    "required_level_counter_2": 0,
+    "custom_data": {
+      "reward": "100 Free Spins",
+      "image_inactive": "https://cdn.example/e917989495185e3fed695d-LevelLevel1Enabledfalse.png",
+      "image_active": "https://cdn.example/a961023ab3f6441ac19dfc-LevelLevel1Enabledtrue.png",
+      "rakeback": 0,
+      "has_vip_club": false,
+      "cashback": 0
+    },
+    "ordinal_position": 1
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getUserProfile`
+- `getUserLevelExtraCounters`
+- `getCurrentLevel`

package/docs/capabilities/getMiniGames.md

@@ -0,0 +1,295 @@
+# getMiniGames — API (TMiniGameTemplate)
+
+> Returns all mini-game templates ("SAW" = Spin And Win — the umbrella term for wheel-spin, scratch-card, lootbox, gift-box, treasure-hunt, plinko, coin-flip, quiz, and several other formats) configured for the label.
+> Import: `import { TMiniGameTemplate } from '@smartico/public-api'`
+> Search terms: getMiniGames, minigames, getSAW, spins, wheel, SAWPrizeType, TMiniGameTemplate, SAWGameTypeName, SAWBuyInTypeName, TMiniGamePrize, MiniGamePrizeTypeName, SAWAcknowledgeTypeName, PrizeModifiers, AttemptPeriodType, SAWTemplateUI, SAWAskForUsername, SAWGameLayoutName, SAWExposeUserSpinIdName, onUpdate, subscription, id, name, description, thumbnail, visibile_when_can_spin, saw_game_type, saw_buyin_type, jackpot_add_on_attempt
+
+## Signature
+```ts
+_smartico.api.getMiniGames({ onUpdate }: { onUpdate?: (data: TMiniGameTemplate[]) => void } = {}): Promise<
+		TMiniGameTemplate[]
+	>
+```
+
+## Parameters
+- `params` — Optional. Omit to fetch without subscribing.
+- `params.onUpdate` — Callback invoked with the full refreshed template array after any spin-count change, spin response, or acknowledge response on this connection.
+
+## Returns — `Promise<
+		TMiniGameTemplate[]
+	>`
+Array of `TMiniGameTemplate`. Each item:
+- `id` (number) — ID of the mini-game template
+- `name` (string) — Name of the mini-game template, translated to the user language
+- `description` (string) — Description of the mini-game template, translated to the user language
+- `thumbnail` (string) — URL of the icon of the mini-game template, 256x256px
+- `visibile_when_can_spin` (boolean) — Indicates if the mini-game is visible when the user have attempts/points/gems/diamonds to play
+- `saw_game_type` (SAWGameTypeName) — The type of the game, e.g. Spin the Wheel, Gift Box, Scratch card, MatchX etc
+- `saw_buyin_type` (SAWBuyInTypeName) — How the user is charged for each game attempt e.g. Free, Points or Spin attempts
+- `buyin_cost_points` (number) — in case of charging type 'Points', what is the points amount will be deducted from user balance
+- `buyin_cost_gems` (number) — in case of charging type 'Gems', what is the gems amount will be deducted from user balance
+- `buyin_cost_diamonds` (number) — in case of charging type 'Diamonds', what is the diamonds amount will be deducted from user balance
+- `spin_count` (number) — in case of charging type 'Spin attempts', shows the current number of spin attempts that user has
+- `next_available_spin_ts` (number) — if the game is limit to the number of spins that user can do during period of time, this property shows the epoch time in UTC when the next attempt will be available. Note that you need to enable 'Show time to the next available spin' setting on mini-game template in the backoffice Important: this field will not be populated if “Max number of attempts a user can do” is set to value different from 1
+- `earliest_expiration_dt` (number | null) — Soonest-expiring spin's expiration time for the current user, as an epoch-ms timestamp. `null` when the user has no expirable spins for this template — spins only expire when the template defines a spin-expiration rule (Wheel of Fortune, Loot Boxes, etc.). Pair with `latest_expiration_dt` to render a "spins expire between X and Y" window.
+- `latest_expiration_dt` (number | null) — Latest-expiring spin's expiration time for the current user, as an epoch-ms timestamp. `null` when the user has no expirable spins; equals `earliest_expiration_dt` when a single expiration applies.
+- `over_limit_message` (string) — The message that should be shown to the user when he cannot play the game, server rejected attempt with error code SAWSpinErrorCode.SAW_FAILED_MAX_SPINS_REACHED
+- `no_attempts_message` (string) — The message that should be shown to the user when he cannot play the game because he doesn't have spin attempts or points.
+- `jackpot_current` (number) — Current jackpont amount, if jackpot is enabled.
+- `jackpot_add_on_attempt` (number) — The amount that will be added to the jackpot every time when somebody plays the game. Note that the contribution amount is abstract, means that no money or points are deducted from the user balance.
+- `jackpot_symbol` (string) — The symbol of jackpot that is giving the sense to the 'amount' E.g. the symbol could be EUR and connected to the amount it can indicate that amount is monetary, e.g. '100 EUR'. Or the symbol can be 'Free spins' and connected to the amount it can indicate that amount is number of free spins, e.g. '100 Free spins'.
+- `promo_image` (string) — The promo image, 500x240px
+- `promo_text` (string) — The promo text
+- `custom_data` (any) — The custom data of the mini-game defined by operator in the BackOffice. Can be a JSON object, string or number
+- `prizes` (TMiniGamePrize[]) — List of prizes for mini-games
+  - `id` (number) — ID of the prize
+  - `name` (string) — The visual name of the prize
+  - `prize_type` (MiniGamePrizeTypeName) — The type of the prize, no-prize, points, bonus, manual, spin, jackpot
+  - `prize_value` (number) — Numeric value of the prize in case it's 'points' or 'spin' type. For other types of prizes this value is not relevant. For example for prize '100 points' the prize_value will be 100. For '100 free spins' the prize_value will be 100.
+  - `font_size` (number) — Custom font size for the prize (desktop)
+  - `font_size_mobile` (number) — Custom font size for the prize (mobile)
+  - `icon` (string) — The URL of the icon of the prize, aspect ratio 1:1
+  - `position` (number) — for scratch card defines position of prize in the list
+  - `sectors` (number[]) — List of sectors for the prize
+  - `acknowledge_type` (SAWAcknowledgeTypeName) — Type of acknowledge message for users
+  - `aknowledge_message` (string) — Message that will be shown to user in modal pop-up
+  - `acknowledge_dp` (string) — Deep link that will trigger some action in modal pop-up
+  - `acknowledge_action_title` (string) — The name of the action button in modal pop-up
+  - `acknowledge_dp_additional` (string) — Deep link that will trigger some action in modal pop-up (additional)
+  - `acknowledge_action_title_additional` (string) — The name of the action button in modal pop-up (additional)
+  - `out_of_stock_message` (string) — Message when the prize pool is empty for that specific prize
+  - `pool` (number) — Number of items in stock
+  - `pool_initial` (number) — Initial number of items in stock
+  - `wins_count` (number) — Number of wins in game
+  - `weekdays` (number[]) — Number of days of week, when the prize can be available
+  - `active_from_ts` (number) — Holds time from which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp)
+  - `active_till_ts` (number) — Holds time till which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp)
+  - `relative_period_timezone` (number) — Time zone to ensure each day aligns with your local midnight.
+  - `is_surcharge` (boolean) — Flag indicating that the prize is surcharged (available all the time, despite pool numbers)
+  - `is_deleted` (boolean) — Flag indicating the state of the prize
+  - `custom_data` (any) — The custom data of the mini-game defined by operator in the BackOffice. Can be a JSON object, string or number
+  - `prize_modifiers` (PrizeModifiers[]) — Prize modifiers that will multiply by 2x, 5x or 10x the current total. This will not affect the final Prize Amount that will be awarded.
+  - `allow_split_decimal` (boolean) — When enabled, you can split prize value by decimal values
+  - `hide_prize_from_history` (boolean) — When enabled, you can hide prize from prize history
+  - `requirements_to_get_prize` (string) — Requirements to claim the prize (lootbox specific)
+  - `max_give_period_type_id` (AttemptPeriodType) — The period type for the prize to be given: Time from last attempt, Calendar days UTC, Calendar days user time zone, Lifetime
+- `expose_game_stat_on_api` (boolean) — When enabled, the number of items in the pool and number of won items will be exposed in the Retention API and in the UI Widgets
+- `relative_period_timezone` (number) — Time zone to ensure each day aligns with your local midnight.
+- `activeFromDate` (number) — Holds time from which template will become available, for the template that are targeted to be available from specific time (UNIX timestamp)
+- `activeTillDate` (number) — Holds time till which template will become available, for the templates that are targeted to be available from specific time (UNIX timestamp)
+- `steps_to_finish_game` (number) — The amount of steps to complete the game and gather the prize
+- `custom_section_id` (number) — Hold the id of the custom section
+- `saw_template_ui_definition` (SAWTemplateUI) — The UI definition of the mini-game
+  - `skin` (string)
+  - `name` (string)
+  - `description` (string)
+  - `over_limit_message` (string)
+  - `hide_prize_names` (string)
+  - `no_attempts_message` (string)
+  - `thumbnail` (string)
+  - `sectors_count` (number)
+  - `priority` (number)
+  - `flow_builder_only` (boolean)
+  - `background_image` (string)
+  - `background_image_mobile` (string)
+  - `background_sound` (string)
+  - `spin_animation_duration` (number)
+  - `scratch_logo` (string)
+  - `scratch_cover` (string)
+  - `scratch_bg_desktop` (string)
+  - `scratch_bg_mobile` (string)
+  - `scratch_cursor` (string)
+  - `custom_css` (string)
+  - `custom_skin_folder` (string)
+  - `jackpot_symbol` (string)
+  - `promo_image` (string)
+  - `promo_text` (string)
+  - `matchx_banner` (string)
+  - `matchx_seasonal_ranking` (boolean)
+  - `matchx_is_completed` (boolean)
+  - `matchx_general_board_users_count` (number)
+  - `matchx_hide_ranking` (boolean)
+  - `prize_pool_image` (string)
+  - `ask_for_username` (SAWAskForUsername)
+  - `show_prize_board` (boolean)
+  - `max_spins_period_ms` (number)
+  - `show_countdown_for_next_availability` (boolean)
+  - `disable_background_music` (boolean)
+  - `custom_section_id` (number)
+  - `only_in_custom_section` (boolean)
+  - `custom_data` (any)
+  - `placeholder1` (string)
+  - `placeholder2` (string)
+  - `prize_drop_template` ({
+		id: string;
+		content: string;
+	})
+- `game_layout` (SAWGameLayoutName) — The layout of the game
+- `show_prize_history` (boolean) — When enabled the prize history icon is visible on a certain template
+- `max_number_of_attempts` (number) — The maximum number of attempts that user can do during period of time
+- `max_spins_period_ms` (number) — The period of time in milliseconds during which the user can do the maximum number of attempts
+- `expose_user_spin_id` (SAWExposeUserSpinIdName) — The ID of the user spin id to expose on the game
+
+## Behavioral contract
+**Subscription model (`onUpdate`)**
+The callback receives the FULL refreshed template list (never a
+diff/patch). Each subsequent call to `getMiniGames({ 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 when:
+
+1. The server pushes a `spin_count` change (campaign award,
+ store purchase, BO manual issuance, mission reward).
+2. Any `playMiniGame` or `playMiniGameBatch`
+ resolves on this connection — the cached array refreshes
+ with updated `spin_count`, `jackpot_current`, and any new
+ `next_available_spin_ts`.
+3. Acknowledge responses land (via auto-acknowledge or
+ `miniGameWinAcknowledgeRequest`).
+
+Jackpot growth is observable on the refreshed `jackpot_current`
+field — the SDK inlines the live value into template `name` /
+`promo_text` / prize `name` via a `{{jackpot}}` template
+substitution at fetch time.
+
+**Game-type variants**
+All twelve `SAWGameType` values (`SpinAWheel`, `ScratchCard`,
+`MatchX`, `GiftBox`, `PrizeDrop`, `Quiz`, `LootboxWeekdays`,
+`LootboxCalendarDays`, `TreasureHunt`, `Voyager`, `Plinko`,
+`CoinFlip`) surface through the same template shape. Most are
+played via `playMiniGame`; the exceptions are:
+- `PrizeDrop` — server-push only; the consumer does NOT call
+ `playMiniGame`. Prizes arrive via the prize-drop push channel.
+- `MatchX` / `Quiz` — predictions are submitted via a separate
+ games server (not this SDK); the SAW spin is fired
+ server-internally to deduct the buy-in.
+
+**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 — `getMiniGames`](../../docs/ui/minigames/UIGuide_getMiniGames.md).
+
+**Visitor mode**: supported. Only templates configured with
+`is_visitor_mode = true` in the BO are returned for anonymous
+sessions. Spins from these templates may also be played (visitor
+mode is the one mini-game flow that does support play — see
+`playMiniGame` for the visitor-stop semantics).
+
+## Example
+```ts
+const games = await window._smartico.api.getMiniGames({
+  onUpdate: (refreshed) => {
+    console.log('[smartico] mini-game templates refreshed — re-render lobby from this array:', refreshed);
+  },
+});
+
+// Filter the lobby view per the visibility flag.
+const visible = games.filter(g =>
+  !g.visibile_when_can_spin || (g.spin_count && g.spin_count > 0)
+);
+
+for (const g of visible) {
+  console.log('[smartico] render game card', g.id, '—', g.name,
+    '— type:', g.saw_game_type,
+    '— buy-in:', g.saw_buyin_type,
+    '— spins available:', g.spin_count ?? 0,
+    '— jackpot:', g.jackpot_current, g.jackpot_symbol);
+}
+```
+
+### 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": 656,
+    "name": "Scratch & Love",
+    "description": "This is demo description of mini game. <br/>\n            <hr/>\n\n            You can <b>use tags</b> like {{spins_available}}, to show number of spins that us…",
+    "thumbnail": "https://cdn.example/00000000-0000-0000-0000-000000000000/ico.png",
+    "visibile_when_can_spin": false,
+    "saw_game_type": "scratch",
+    "saw_buyin_type": "spins",
+    "jackpot_add_on_attempt": 1,
+    "jackpot_current": 1070,
+    "spin_count": 5,
+    "promo_image": "https://cdn.example/d3d65f1bc722a8c66a9493-PromoImagefromTinyPNG.png",
+    "promo_text": "The Scratch of Love is better than any other scratch!",
+    "custom_data": {},
+    "expose_game_stat_on_api": false,
+    "relative_period_timezone": 0,
+    "activeFromDate": -9223372036854776000,
+    "activeTillDate": 9223372036854776000,
+    "next_available_spin_ts": null,
+    "earliest_expiration_dt": 1952155860877,
+    "latest_expiration_dt": 1952155860877,
+    "custom_section_id": 491,
+    "saw_template_ui_definition": {
+      "scratch_bg_mobile": "",
+      "promo_text": "The Scratch of Love is better than any other scratch!",
+      "thumbnail": "",
+      "only_in_custom_section": false,
+      "scratch_logo": "",
+      "description": "This is demo description of mini game. <br/>\n            <hr/>\n\n            You can <b>use tags</b> like {{spins_available}}, to show number of spins that us…",
+      "background_image_mobile": "",
+      "custom_css": ".scratch-card-root-mobile .scratch-area .button-area div {\n    background-image: linear-gradient(180deg,#BD0A42,50%,#BD0A42);\n}\n.scratch-card-root .scratch-a…",
+      "hide_prize_names": false,
+      "scratch_bg_desktop": "",
+      "priority": 1,
+      "scratch_cover": "",
+      "background_image": "",
+      "sectors_count": 6,
+      "show_countdown_for_next_availability": false,
+      "promo_image": "https://cdn.example/d3d65f1bc722a8c66a9493-PromoImagefromTinyPNG.png",
+      "disable_background_music": true,
+      "scratch_cursor": "",
+      "background_sound": "",
+      "name": "Scratch & Love",
+      "spin_animation_duration": 15,
+      "flow_builder_only": false,
+      "custom_section_id": 491,
+      "background_music_volume": 10
+    },
+    "show_prize_history": true,
+    "max_number_of_attempts": 0,
+    "prizes": [
+      {
+        "id": 15589,
+        "name": "No luck this time =(",
+        "prize_type": "no-prize",
+        "prize_value": 1,
+        "font_size": null,
+        "position": 7,
+        "sectors": [
+          ""
+        ],
+        "acknowledge_type": "silent",
+        "acknowledge_dp": "dp:ok",
+        "acknowledge_action_title": "OK",
+        "pool": null,
+        "pool_initial": 100,
+        "wins_count": null,
+        "weekdays": null,
+        "active_from_ts": null,
+        "active_till_ts": null,
+        "relative_period_timezone": 0,
+        "is_surcharge": false,
+        "is_deleted": false,
+        "custom_data": {},
+        "max_give_period_type_id": 2
+      }
+    ]
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `playMiniGame`
+- `playMiniGameBatch`
+- `miniGameWinAcknowledgeRequest`

package/docs/capabilities/getMiniGamesHistory.md

@@ -0,0 +1,183 @@
+# getMiniGamesHistory — API (TSawHistory)
+
+> Returns a paginated, newest-first list of the user's past mini-game spins — each row carries the won prize ID, the client-side `request_id` used for the spin, and a server-recorded `is_claimed` flag (`true` if the spin has been acknowledged).
+> Import: `import { TSawHistory } from '@smartico/public-api'`
+> Search terms: getMiniGamesHistory, minigames, getSAWHistory, TSawHistory, SAWTemplate, SAWGameType, SAWTemplateUI, SAWBuyInType, SAWPrize
+
+## Signature
+```ts
+_smartico.api.getMiniGamesHistory({
+		limit,
+		offset,
+		saw_template_id,
+	}: {
+		limit?: number;
+		offset?: number;
+		saw_template_id?: number;
+	}): Promise<TSawHistory[]>
+```
+
+## Parameters
+- `params` — Optional pagination + filter bag.
+- `params.limit` — Page size. Defaults to 20.
+- `params.offset` — Number of rows to skip. Defaults to 0.
+- `params.saw_template_id` — When set, scopes the history to a single template's spins.
+
+## Returns — `Promise<TSawHistory[]>`
+Array of `TSawHistory`. Each item:
+- `template` (SAWTemplate) — The initial information about mini-game
+  - `saw_template_id` (number)
+  - `saw_game_type_id` (SAWGameType)
+  - `saw_template_ui_definition` (SAWTemplateUI)
+    - `skin` (string)
+    - `name` (string)
+    - `description` (string)
+    - `over_limit_message` (string)
+    - `hide_prize_names` (string)
+    - `no_attempts_message` (string)
+    - `thumbnail` (string)
+    - `sectors_count` (number)
+    - `priority` (number)
+    - `flow_builder_only` (boolean)
+    - `background_image` (string)
+    - `background_image_mobile` (string)
+    - `background_sound` (string)
+    - `spin_animation_duration` (number)
+    - `scratch_logo` (string)
+    - `scratch_cover` (string)
+    - `scratch_bg_desktop` (string)
+    - `scratch_bg_mobile` (string)
+    - `scratch_cursor` (string)
+    - `custom_css` (string)
+    - `custom_skin_folder` (string)
+    - `jackpot_symbol` (string)
+    - `promo_image` (string)
+    - `promo_text` (string)
+    - `matchx_banner` (string)
+    - `matchx_seasonal_ranking` (boolean)
+    - `matchx_is_completed` (boolean)
+    - `matchx_general_board_users_count` (number)
+    - `matchx_hide_ranking` (boolean)
+    - `prize_pool_image` (string)
+    - `ask_for_username` (SAWAskForUsername)
+    - `show_prize_board` (boolean)
+    - `max_spins_period_ms` (number)
+    - `show_countdown_for_next_availability` (boolean)
+    - `disable_background_music` (boolean)
+    - `custom_section_id` (number)
+    - `only_in_custom_section` (boolean)
+    - `custom_data` (any)
+    - `placeholder1` (string)
+    - `placeholder2` (string)
+    - `prize_drop_template` ({
+		id: string;
+		content: string;
+	})
+  - `saw_buyin_type_id` (SAWBuyInType)
+  - `buyin_cost_points` (number)
+  - `visibile_when_can_spin` (boolean)
+  - `spin_count` (number)
+  - `prizes` (SAWPrize[])
+    - `saw_prize_id` (number)
+    - `saw_prize_ui_definition` (SAWPrizeUI)
+      - `position` (number)
+      - `name` (string)
+      - `name_original` (string)
+      - `hide_prize_popup` (boolean)
+      - `aknowledge_message` (string)
+      - `sectors` (number[])
+      - `acknowledge_type` (SAWAcknowledgeType)
+      - `acknowledge_dp` (string)
+      - `font_size` (number)
+      - `font_size_mobile` (number)
+      - `sound_type` (SAWWinSoundType)
+      - `icon` (string)
+      - `replace_name_with_image` (boolean)
+      - `acknowledge_action_title` (string)
+      - `custom_win_sound` (string)
+    - `prize_value` (number)
+    - `prize_type_id` (SAWPrizeType)
+    - `place_from` (number)
+    - `place_to` (number)
+    - `sawUniqueWinId` (string)
+  - `is_visible` (boolean)
+  - `jackpot_add_on_attempt` (number)
+  - `jackpot_current` (number)
+  - `jackpot_guaranteed` (number)
+  - `maxActiveSpinsAllowed` (number)
+  - `maxSpinsCount` (number)
+  - `maxSpinsPediodMs` (number)
+  - `next_available_spin_ts` (number)
+  - `saw_skin_key` (string)
+  - `saw_skin_ui_definition` ({
+		skin_folder: string;
+		skin_css: string;
+	})
+- `saw_template_id` (number) — ID of the mini-game template
+- `saw_prize_id` (number) — The saw_prize_id that user won, details of the prize can be found in the mini-game definition
+- `prize_amount` (number) — Amount of prizes in stock
+- `client_request_id` (string) — Request ID that client is sending to show history
+- `is_claimed` (boolean) — Flag indicating to show whether prize in the mini-game claimed or not
+- `create_date_ts` (number) — Win prize date in milliseconds
+- `acknowledge_date_ts` (number) — Claimed prize date in milliseconds
+
+## Behavioral contract
+**Pagination**
+`limit` defaults to 20, `offset` defaults to 0. Sort order is
+`create_date` DESC (newest first) — no client-side re-sort
+required. For "load more" pagination, advance `offset` by the
+page size on each subsequent call.
+
+The underlying protocol carries a `hasMore` boolean on the
+response, but the SDK strips it from the public surface —
+detect end of list when the returned array length is less than
+`limit`.
+
+**`is_claimed` semantics**
+Maps directly to the server's "acknowledge_date is non-null"
+state. A spin where the auto-acknowledge fire-and-forget
+succeeded shows `is_claimed: true`; a spin where the
+acknowledge was lost (network drop) or where the user is on an
+explicit-acknowledge flow shows `is_claimed: false` with a
+usable `client_request_id`. A server-side fallback job
+auto-acknowledges stale rows every ~60 seconds — so even
+"lost" prizes are eventually delivered without consumer action.
+
+**Cache TTL**: the SDK caches the response for 30 seconds.
+Cache is invalidated implicitly when a new spin or acknowledge
+response lands.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getMiniGamesHistory`](../../docs/ui/minigames/UIGuide_getMiniGamesHistory.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
+
+// Show unacknowledged spins with a Claim CTA.
+const unacknowledged = history.filter(h => !h.is_claimed);
+console.log('[smartico] surface a "Claim" CTA on these', unacknowledged.length, 'history rows:',
+  unacknowledged.map(h => h.client_request_id));
+
+// Load-more pagination — advance offset by the prior page size.
+const page2 = await window._smartico.api.getMiniGamesHistory({ limit: 20, offset: 20 });
+console.log('[smartico] page 2 loaded —', page2.length, 'more rows;',
+  page2.length < 20 ? 'end of list reached, hide "Load more"' : 'keep "Load more" visible');
+```
+
+### 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
+- `miniGameWinAcknowledgeRequest`