@smartico/public-api 0.0.379 → 0.0.381

package/docs/ui/leaderboard/UIGuide_getLeaderBoard.md

@@ -0,0 +1,166 @@
+# UI Guide — `getLeaderBoard`
+
+## Overview
+- Returns the top-20 ranked entries for one period, the current user's
+  own rank, and the configured prize table.
+- One call per (period type, current-or-previous) — the SDK caches
+  under a single key, so switching periods or current/previous within
+  30 s returns stale cached data unless `clearCaches()` is invoked.
+- No subscription, no push refresh. Poll manually if the consumer
+  needs live updates during an in-progress period.
+
+## List view organization
+
+The default Smartico UI renders the leaderboard with three top-level
+tabs inside the page:
+
+| Tab | Content |
+|---|---|
+| **Leaders** | The ranked `users[]` list + sticky "me" row |
+| **Prizes** | The `rewards[]` table — one row per paid place |
+| **Rules** | The `rules` HTML (operator-defined terms) |
+
+A separate **period selector** sits above the tabs — one tab per
+configured board (DAILY / WEEKLY / MONTHLY). Switching periods
+dispatches a new `getLeaderBoard()` call.
+
+A **current ↔ previous** toggle button sits below the Leaders list.
+Label depends on the active period: "Yesterday's winners" /
+"Last week's winners" / "Previous month's winners" / "Today's
+leaders" / "Current standings".
+
+## Rank table layout
+
+Columns per row (in the Leaders tab):
+
+| Column | Source | Notes |
+|---|---|---|
+| Position | `user.position` | Server-computed DENSE_RANK. Show as `01`, `02`, … `20`. |
+| Avatar | `user.avatar_url` | Hide via operator config `hide_avatars_leaderboards` if applicable. |
+| Username | `user.public_username` | |
+| Points | `user.points` | Operator config `leaderboard_hide_other_points` may suppress points for everyone except the current user. |
+| Level badge | (Drives from separate `getCurrentLevel` lookup, not on this type) | Operator config `leaderboard_hide_levels` may suppress. |
+
+**Top-3 podium styling**: apply distinct CSS classes (`place-1`,
+`place-2`, `place-3`) to rows with `position <= 3` (and
+`position !== -1`). The default Smartico UI uses CSS-only treatment
+— no podium banner or 1st/2nd/3rd icons.
+
+**Desktop padding**: when `users.length < 8`, the default UI pads the
+list height with a vertical spacer so the card height stays stable
+across periods. Skip this on mobile.
+
+## "Me" sticky row
+
+`board.me` is the current authenticated user's entry. Render rules:
+
+- **Visitor mode**: `me` is `undefined` — skip the sticky row.
+- **`me.position === -1`**: the user has not yet accumulated points
+  this period (or is otherwise unranked). Show a friendly state:
+  `"You're unranked — earn points to climb the board"`.
+- **`me.position > 0` AND visible in `users[]` (top 20)**: highlight
+  the matching row in the main list (CSS class). The default
+  Smartico UI also keeps a sticky bottom row for consistency.
+- **`me.position > 20`**: pin the sticky bottom row with the user's
+  rank, avatar, username, and points. The default Smartico UI shows
+  this on desktop only (mobile uses a stub spacer to keep layout
+  height stable but does not render the sticky row).
+
+## Prize table (Prizes tab)
+
+Render `rewards[]` as a two-column table:
+
+| Column | Source |
+|---|---|
+| Place | `reward.place` (e.g. `1`, `2`, `3`) formatted as "1st place", "2nd place", etc. — use the locale's plural-ordinal helper for proper rendering. |
+| Prize | `reward.points` formatted with locale separators + the brand's points unit (e.g. `"100 points"`, `"1,000 pts"`). |
+
+Show in order — the first array element is place 1.
+
+The default Smartico UI does NOT inline rewards on the main leaders
+list (only in the dedicated Prizes tab). Custom UIs may want to
+inline a hint on the top-3 rows.
+
+## Rules tab
+
+Render `board.rules` as sanitized HTML. The default Smartico UI uses
+`dangerouslySetInnerHTML` — **sanitize before injecting** to
+prevent XSS if your product surface is exposed to untrusted operator
+content.
+
+## Period selector (current ↔ previous)
+
+When the user switches between current and previous period:
+
+1. Call `clearCaches()` to bust the shared OCache key
+   (otherwise the second call returns stale data within 30 s).
+2. Call `getLeaderBoard(periodType, getPreviousPeriod)` with the new
+   `getPreviousPeriod` value.
+3. Replace the rendered data.
+
+```ts
+const onTogglePrevious = async (showPrevious: boolean) => {
+  await window._smartico.api.clearCaches();
+  const board = await window._smartico.api.getLeaderBoard(
+    activePeriodType,
+    showPrevious,
+  );
+  console.log('[smartico] switched to', showPrevious ? 'previous' : 'current', 'period — re-render with this board:', board);
+};
+```
+
+Same pattern applies when switching between period types
+(`DAILY` → `WEEKLY` → `MONTHLY`).
+
+## Status-specific visual treatments
+
+- **Current period**: full-color rendering; live point counts.
+- **Previous period** (`getPreviousPeriod: true`): identical
+  rendering — the default Smartico UI does not visually
+  differentiate. Custom UIs may want to apply subtle desaturation
+  or an "ENDED" pill to signal that the rankings are final.
+- **Unranked `me`** (`position === -1`): friendly "earn points to
+  enter the board" copy in the sticky panel.
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: render a skeleton table (8 placeholder
+  rows) sized to the eventual layout. The default Smartico UI uses
+  a `Loader` spinner.
+- **Empty `users[]`**: render a Lottie / static illustration with
+  copy like "No Leaders Yet". Common early in a fresh period.
+- **`board === undefined`** (no board configured for this period):
+  hide the leaderboard surface entirely or surface a neutral
+  "Leaderboard not available" message.
+- **Error**: keep the prior list if any; show a non-blocking error
+  banner; retry on the next user-driven action.
+
+## Animations / transitions
+
+- **Initial fade-in**: rows fade in on first paint.
+- **Rank change between fetches**: the default Smartico UI does NOT
+  animate rank changes — rows re-render in-place. Custom UIs that
+  poll may want to diff snapshots and apply a FLIP animation to
+  highlight position movement.
+- **Period switch**: cross-fade table contents (~150 ms ease-out).
+
+## Mobile vs desktop
+
+- **Period tab strip**: desktop uses a standard tab component;
+  mobile uses a scrollable custom-styled strip.
+- **Sticky "me" row**: desktop renders it; mobile renders only a
+  stub spacer (no sticky row, to save vertical space).
+- **Desktop padding**: list height padded to ≥ 8 rows; mobile does
+  not pad.
+
+## Performance
+
+- The 30 s cache deduplicates rapid refetches, but the single-key
+  design means switching periods within the window returns stale
+  data. `clearCaches()` is the only way to force a fresh fetch
+  before the TTL expires.
+- For live polling during an in-progress period, ~30 s cadence is
+  appropriate (matching the cache TTL — additional polls within
+  the window are free).
+- The leaderboard list is small (max 20 rows + 1 me row); no
+  virtualization needed.

package/docs/ui/minigames/UIGuide_getMiniGames.md

@@ -0,0 +1,153 @@
+# UI Guide — `getMiniGames`
+
+## Overview
+- Returns the operator-configured mini-game templates ("SAW" =
+  Spin And Win — covers wheel, scratch card, lootbox, gift box,
+  treasure hunt, plinko, coin flip, quiz, and several other formats).
+- Templates carry per-user state (`spin_count`,
+  `next_available_spin_ts`, `jackpot_current`) — these update via
+  `onUpdate` after any spin / acknowledge / server-pushed grant.
+- The list is NOT filtered by spin availability — apply
+  `visibile_when_can_spin` client-side to hide templates the user
+  can't currently play.
+- Visitor mode supported.
+
+## List view organization
+
+The default Smartico UI presents mini-game templates as a **flat
+list** (no per-game-type tabs). Templates of different
+`saw_game_type` values appear together, sorted by the operator's
+configured priority.
+
+Client-side visibility filter:
+
+```ts
+const visible = games.filter(g =>
+  !g.visibile_when_can_spin || (g.spin_count && g.spin_count > 0)
+);
+```
+
+`visibile_when_can_spin` is operator-configured per template. When
+`true`, the template should be hidden from the lobby until the user
+has spins (or balance for paid templates).
+
+## Item card
+
+Fields rendered per game card:
+
+| Field | Source | Notes |
+|---|---|---|
+| Thumbnail | `thumbnail` (256×256 px source from template UI definition) | Render at 1:1 aspect ratio. |
+| Name | `name` | Server-side `{{jackpot}}` substitution inlines the live jackpot value. |
+| Description | `description` | Short marketing tagline. |
+| Game-type pill | `saw_game_type` | E.g. "Spin", "Scratch", "Lootbox" — translate the enum value to a display label. |
+| Spin-count badge | `spin_count` (only when `saw_buyin_type === 'spins'`) | Show as a chip on the card. |
+| Buy-in indicator | `saw_buyin_type` + `buyin_cost_points` / `_gems` / `_diamonds` | "Free", "100 pts", "5 gems", etc. |
+| Jackpot display | `jackpot_current` + `jackpot_symbol` | Only when `jackpot_add_on_attempt > 0`. Animate the value count-up when it changes via push. |
+| Promo image | `promo_image` (500×240 px) | Optional larger artwork for featured / hero rendering. |
+| Countdown | `next_available_spin_ts` (epoch ms) | Show "Available in HH:MM:SS" when set and in the future. |
+| Play CTA | (derived) | See "Action button decision matrix". |
+
+**Whole-card click target**: opens the detail / play view for that
+template.
+
+## Detail / play view per game type
+
+The `saw_game_type` value drives the renderer:
+
+| `SAWGameType` | Renderer | Behavior |
+|---|---|---|
+| `SpinAWheel` (1) | Canvas wheel; spin to a stop position on a 360° track | ~15 s animation; bezier ease-out |
+| `ScratchCard` (2) | Canvas scratch-off reveal | User drags / taps to scratch; prize revealed underneath |
+| `MatchX` (3) | Score-prediction UI (separate games server) | DON'T call `playMiniGame` — the games server fires the spin internally |
+| `GiftBox` (4) | Tap-to-reveal gift boxes | Bubbles layout; tap chooses a box |
+| `PrizeDrop` (5) | None (push-only) | Don't call `playMiniGame`; prizes arrive via push |
+| `Quiz` (6) | Q&A UI (separate games server) | DON'T call `playMiniGame` |
+| `LootboxWeekdays` (7) | Pick-N-from-grid | Grid layout or vertical-map (`game_layout` determines) |
+| `LootboxCalendarDays` (8) | Pick-N-from-grid | Same; pool filtered to current calendar date |
+| `TreasureHunt` (9) | Map exploration | `steps_to_finish_game` cells |
+| `Voyager` (10) | Journey UI | `min_steps_to_finish_game` floor |
+| `Plinko` (11) | Physics ball-drop | Animated drop through pegs |
+| `CoinFlip` (12) | Binary coin flip | Heads-or-tails reveal |
+
+The default Smartico UI uses a lazy-loaded component dispatcher
+keyed on `saw_game_type`. For custom UIs, render the matching
+component per game type — they share the same `playMiniGame`
+trigger (except `PrizeDrop`, `MatchX`, `Quiz` as noted).
+
+## Action button decision matrix
+
+CTA on the card / detail view (evaluate in priority order):
+
+| Condition | CTA | Notes |
+|---|---|---|
+| `next_available_spin_ts > now` | "Available in HH:MM:SS" (countdown, disabled) | Countdown to next allowed spin |
+| `saw_buyin_type === 'spins'` AND `spin_count === 0` | "No spins" (disabled) | Show `no_attempts_message` from the template |
+| Insufficient balance (paid templates) | "Not enough {currency}" (disabled) | Compare `buyin_cost_*` against `getUserProfile` balance |
+| User not in segment / template expired | (hidden — server filtered) | Template typically excluded by server visibility |
+| Default (playable) | "Play" / "Spin" | Enabled — invokes `playMiniGame` |
+
+`over_limit_message` and `no_attempts_message` are operator-supplied
+messages; surface them under the disabled CTA rather than a generic
+error.
+
+## Image / asset specs
+
+| Field | Aspect | Notes |
+|---|---|---|
+| `thumbnail` | 1:1 (square), 256×256 px | Card icon |
+| `promo_image` | ~2:1 wide, 500×240 px | Featured / hero artwork |
+| `prizes[].icon` | 1:1 (square) | Per-prize icon |
+
+## Status-specific visual treatments
+
+- **Playable**: full-color card; Play CTA enabled.
+- **No spins / insufficient balance**: card desaturated or dimmed;
+  CTA disabled with operator message.
+- **Countdown**: card normal; CTA replaced with countdown timer
+  (update every second).
+- **`visibile_when_can_spin` filter**: card hidden entirely.
+- **Jackpot increasing live**: pulse / glow the jackpot value when
+  it ticks up via push (detect by diffing previous snapshot in
+  `onUpdate`).
+
+## Countdown / timing format
+
+`next_available_spin_ts` — epoch ms — drives the countdown. Use:
+
+- `> 1 hour` → `"HH:MM"` ("01:23")
+- `1 minute – 1 hour` → `"MM:SS"`
+- `< 1 minute` → `"0:SS"`, ticking down per second
+
+Update once per second while visible. Hide the countdown and show
+the Play CTA when the timestamp passes.
+
+## Empty / loading / error states
+
+- **Loading**: skeleton grid (3–6 placeholder cards).
+- **Empty**: `[]` means no templates configured. Render a neutral
+  empty-state.
+- **Error**: keep prior list if any; show non-blocking error banner.
+
+## Animations / transitions
+
+- **Card entry**: fade-in stagger.
+- **Jackpot tick**: count-up animation when value increases via
+  push (detected by diffing prior snapshot in `onUpdate`).
+- **Spin-count flash**: highlight the spin-count badge when it
+  changes (campaign grant, prize win that grants spins).
+
+## Mobile vs desktop
+
+- **Card density**: desktop 3–4 columns; mobile 2 columns
+  (sometimes 1 for large promo cards).
+- **Detail view**: desktop centered modal; mobile full-screen.
+- **Game canvas**: scales with viewport.
+
+## Performance
+
+- 30 s cache deduplicates rapid refetches.
+- Diff snapshots in `onUpdate` to detect jackpot / spin-count
+  changes for animations.
+- Lazy-load game-type renderers (each game type is a substantial
+  component bundle).

package/docs/ui/minigames/UIGuide_getMiniGamesHistory.md

@@ -0,0 +1,90 @@
+# UI Guide — `getMiniGamesHistory`
+
+## Overview
+- Paginated, newest-first list of past spins. Each row carries the
+  won prize ID, the spin's `client_request_id`, an `is_claimed`
+  flag, and the template that produced it.
+- Use to power a "My prizes" / win-history surface, and to surface
+  Claim CTAs on unacknowledged spins (`is_claimed === false`).
+- 30 s cache. No subscription / push refresh.
+
+## List view organization
+
+Single flat list, server-sorted newest-first by spin creation
+timestamp. No client-side re-sort required. No tabs in the default
+Smartico UI — but a custom UI might tab by:
+
+- "Claimed" vs "Unclaimed" (filter by `is_claimed`)
+- Per-template (use `saw_template_id` filter argument)
+
+## Item card / row
+
+Fields rendered per row:
+
+| Field | Source | Notes |
+|---|---|---|
+| Template icon | `template.thumbnail` (or similar) | 1:1 |
+| Prize name | Look up `template.prizes[i]` by `saw_prize_id` | Display the prize's `name`. |
+| Prize amount | `template.prizes[i].prize_value` or `prize_amount` | E.g. "100 points" |
+| Spin date | `create_date_ts` | Format as user-local relative time ("2h ago") or short date |
+| Claim status | `is_claimed` | Show check-mark when true; "Pending claim" CTA when false |
+| Acknowledge date | `acknowledge_date_ts` | Only when `is_claimed === true` |
+
+**Click target**: typically opens the template detail / play view
+(to "play again" or read prize terms). Optional.
+
+## Action button — Claim CTA on unacknowledged rows
+
+When `is_claimed === false`, render a "Claim" button:
+
+```ts
+const onClaimHistoryRow = async (row: TSawHistory) => {
+  await window._smartico.api.miniGameWinAcknowledgeRequest(row.client_request_id);
+  console.log('[smartico] re-acknowledged spin — refresh history list to flip is_claimed');
+  const refreshed = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
+  // ...
+};
+```
+
+Note: a server-side fallback job auto-acknowledges stale spins
+every ~60 seconds, so unclaimed rows usually self-resolve without
+explicit user action. The manual Claim CTA is for instant recovery
+when the user is actively viewing the history surface.
+
+## Pagination
+
+`limit` defaults to 20; `offset` defaults to 0. For load-more
+pagination, advance `offset` by the prior page size. Detect end of
+list when the returned array length is less than `limit`.
+
+`saw_template_id` filter scopes to a single template's history —
+useful for a per-game "previous wins" panel.
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: skeleton list (3–5 placeholder rows).
+- **Empty**: "No mini-game history yet" with optional illustration.
+- **Empty (filtered)**: "No history for this game".
+- **Error**: keep prior list if any; non-blocking error banner.
+
+## Refresh
+
+No subscription / push refresh. Re-call after:
+
+- A successful `playMiniGame` / `playMiniGameBatch` to surface the
+  new row at the top.
+- A successful `miniGameWinAcknowledgeRequest` to flip `is_claimed`.
+
+The 30 s cache deduplicates rapid refetches.
+
+## Mobile vs desktop
+
+- **Row density**: identical on both.
+- **Claim CTA**: inline button on each row (both platforms).
+
+## Performance
+
+- The 30 s cache helps when the user navigates between tabs and
+  re-renders the history.
+- Don't over-fetch — limit to 20–50 rows per page.
+- Filter by `saw_template_id` when the surface is per-template.

package/docs/ui/minigames/UIGuide_playMiniGame.md

@@ -0,0 +1,150 @@
+# UI Guide — `playMiniGame`
+
+## Overview
+- Action-focused mutation. User clicks "Play" / "Spin" on a mini-
+  game card; the server runs the prize selection and returns the
+  won prize.
+- Auto-acknowledges on success (fire-and-forget) — most consumers
+  don't need to handle acknowledge manually.
+- The SDK does NOT prevent double-clicks at the public API level;
+  guard the call site.
+
+## Loading state — the game animation IS the loading state
+
+For most mini-game types, the **game animation itself serves as the
+loading state**. Start the animation immediately on click (before
+the response arrives); the server response arrives during the
+animation; sync the final reveal to land at the animation's end
+position.
+
+Typical animation durations by game type:
+
+- Wheel: ~15 s (long enough to mask any reasonable latency)
+- Scratch card: user-driven (no time pressure)
+- Lootbox: ~3 s (open animation)
+- Gift box: ~2 s (reveal)
+- Treasure hunt / Voyager / Plinko / Coin flip: ~2–5 s
+- Match X / Quiz: not applicable (separate game server)
+
+If the server response arrives late (network slow), pause the
+animation or hold at a "still spinning" loop until the result
+lands.
+
+## Idempotency guard
+
+The SDK does NOT prevent double-clicks. Guard the call site:
+
+```ts
+const [playing, setPlaying] = useState(false);
+
+const onPlay = async () => {
+  if (playing) return;
+  setPlaying(true);
+  startAnimation();
+  const r = await window._smartico.api.playMiniGame(template_id);
+  syncAnimationToResult(r);
+  setPlaying(false);
+  handleResult(r);
+};
+```
+
+**Don't skip this guard** — a double-tap deducts the buy-in twice.
+The server has its own per-user-per-template lock that serialises
+concurrent requests, but it still processes both sequentially.
+
+## Action button decision matrix
+
+UI behavior per `err_code`:
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Animate the result; show acknowledge modal per `template.acknowledge_type` (see below); refresh balance widgets. |
+| `40001` (no spins) | Disable Play; show `no_attempts_message` from the template. |
+| `40002` (prize pool empty) | Disable Play; show "All prizes claimed for now". |
+| `40003` (insufficient points) | Disable Play; show insufficient-balance UI naming the deficit. |
+| `40004` (max spins reached) | Show countdown to next available spin. `first_spin_in_period` is on the batch result type; for the single-play path, derive next-available from `template.next_available_spin_ts`. |
+| `40007` (template not active) | Disable / hide the template. |
+| `40009` (segment mismatch / lootbox empty for today) | Hide the template OR show "Not available today" for lootboxes. |
+| `40011` / `40012` (insufficient gems / diamonds) | Same as `40003` for the matching currency. |
+| `-40001` (visitor stopped) | Silently end the game; no prize modal. Default Smartico UI doesn't surface this as an error. |
+| Other non-zero | Show generic error toast. Allow retry. |
+
+## Prize reveal modals
+
+`template.acknowledge_type` controls the post-animation modal:
+
+| Value | Behavior |
+|---|---|
+| `Silent` (1) | No modal; auto-acknowledge fires silently. |
+| `QuickMessage` (2) | Toast popup; auto-closes after ~5 s; auto-acknowledge fires. |
+| `FullMessage` (3) | Full-screen modal; user dismisses; auto-acknowledge fires. |
+| `ExplicitAcknowledge` (4) | Modal with explicit "Claim" CTA; acknowledge sends only on tap. Use this for high-value or lootbox-style rewards. |
+
+For `ExplicitAcknowledge`, suppress the SDK's auto-acknowledge by
+NOT using this method's `playMiniGame` directly — call the
+acknowledge via [`miniGameWinAcknowledgeRequest`](../../api/classes/WSAPIMiniGames.md#minigamewinacknowledgerequest)
+when the user taps Claim. (The SDK still auto-fires the
+acknowledge from `playMiniGame`, but the visual gate is still
+meaningful.)
+
+Modal contents per prize:
+
+- Icon: `prize.icon` (1:1)
+- Title: `prize.name`
+- Message: `prize.aknowledge_message` (note the typo in the field
+  name — `aknowledge` not `acknowledge`)
+- CTA: `prize.acknowledge_action_title` with action
+  `prize.acknowledge_dp` (pass through `_smartico.dp()` for safe
+  execution)
+- Optional additional CTA: `prize.acknowledge_action_title_additional`
+  + `prize.acknowledge_dp_additional`
+
+## "No prize" handling
+
+When the won prize has `prize_type === 'no-prize'`, the user has
+"lost" — the buy-in was still deducted. Show a friendly "Better
+luck next time" treatment rather than a celebration. The operator
+configures these slots intentionally — they're not errors.
+
+## Refresh after success
+
+The SDK auto-refreshes the templates cache after every spin. The
+`onUpdate` callback registered via `getMiniGames` fires with the
+updated array — observe the new `spin_count`, `jackpot_current`,
+and `next_available_spin_ts`.
+
+The user's balance updates (points / gems / diamonds credited from
+prize wins) flow via
+[`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)'s
+`props_change` channel.
+
+## Per-game-type animation nuances
+
+| Game type | Animation pattern |
+|---|---|
+| Spin a Wheel | Start spinning on click; sync the final position to land on the won prize sector at ~15 s. Cubic-bezier deceleration. |
+| Scratch Card | User-driven; the won prize is hidden under the scratch layer. Reveal at scratch completion threshold (~60% scratched). |
+| Gift Box | All boxes shake on play; user taps to "open" their chosen box; the won prize appears in the tapped box. |
+| Lootbox (Weekdays / CalendarDays) | Grid layout; user picks N from grid; pre-determined positions reveal the won prize. |
+| Treasure Hunt | Multi-step map; each play advances one step; final step reveals the prize. |
+| Voyager | Journey-style multi-step. |
+| Plinko | Ball drops through pegs; landing position determines the won prize. Physics-driven path or pre-computed to match server result. |
+| Coin Flip | Binary heads/tails reveal. |
+
+The default Smartico UI ships components for all these — for
+custom UIs, the consumer is responsible for the animation per type.
+
+## Mobile vs desktop
+
+- **Game canvas**: scales with viewport.
+- **Modal**: desktop centered with backdrop; mobile full-screen.
+- **Touch targets**: mobile needs 44×44 px minimum for game
+  interactions.
+
+## Performance
+
+- Single round-trip per spin.
+- Pre-load game animation assets at template card render time so
+  the animation starts immediately on click.
+- The `onUpdate` callback fires after each spin — use it to refresh
+  the card's spin_count badge.

package/docs/ui/minigames/UIGuide_playMiniGameBatch.md

@@ -0,0 +1,128 @@
+# UI Guide — `playMiniGameBatch`
+
+## Overview
+- Plays the same template `spin_count` times in a single
+  round-trip. Returns an array of per-spin results.
+- Each result is independent — the server does NOT roll back on
+  partial failures.
+- Use for "Spin N times" / "Open N lootboxes" affordances.
+
+## Result shape note
+
+`TMiniGamePlayBatchResult` uses **camelCase** `errCode` /
+`errMessage` (differs from `TMiniGamePlayResult` which uses
+`err_code` / `err_message`). Branch on the camelCase keys.
+
+## Loading state
+
+For multi-spin batches, the UI needs to choose between:
+
+1. **Sequential animation** — animate each spin one at a time using
+   the response array as the "script". The default Smartico UI
+   uses this pattern for multi-spin lootboxes. ~2-3 s per spin.
+2. **Bulk reveal** — animate all spins in parallel (faster but
+   visually busy). Suitable for "open 10 lootboxes" power-user
+   affordances.
+3. **Skip animation** — show a results table immediately.
+   Suitable for "auto-spin N" power affordances.
+
+Set an in-flight flag on click; clear it when the response lands
+AND any animation completes.
+
+## Idempotency guard
+
+Same as `playMiniGame` — guard against double-clicks. A
+double-tap sends two batches, each deducting `spin_count` worth of
+buy-in.
+
+## Per-spin result handling
+
+Iterate `results[]` and handle each result independently:
+
+```ts
+for (const [i, r] of results.entries()) {
+  if (r.errCode === 0) {
+    const prize = template.prizes.find(p => p.id === r.saw_prize_id);
+    if (prize?.prize_type === 'no-prize') {
+      console.log('[smartico] spin', i, 'lost');
+    } else {
+      console.log('[smartico] spin', i, 'won:', prize?.name);
+    }
+  } else if (r.errCode === 40001) {
+    console.log('[smartico] spin', i, '— no spins left; abort the rest of the animation early');
+    break;
+  } else if (r.errCode === 40004) {
+    const msTillNext = template.max_spins_period_ms! - (Date.now() - (r.first_spin_in_period ?? 0));
+    console.log('[smartico] spin', i, 'capped — ' + Math.ceil(msTillNext / 1000) + 's until next');
+  } else {
+    console.error('[smartico] spin', i, 'failed:', r.errMessage);
+  }
+}
+```
+
+## Partial-success handling
+
+Common scenario: user requests 5 spins but only has 3 spin
+tickets. Results[0–2] succeed; results[3–4] fail with
+`SAW_NO_SPINS`.
+
+UI options:
+
+- Show all 3 successful prizes; then surface a "You ran out of
+  spins" message for the remaining 2 attempts.
+- Or skip the failed animations entirely and only render the
+  successful results.
+
+The default Smartico UI shows successful results then a brief
+"No more spins" toast.
+
+## `first_spin_in_period` for cooldown UX
+
+When any result has `errCode === SAW_FAILED_MAX_SPINS_REACHED`
+(40004), the result's `first_spin_in_period` field carries the
+epoch ms of the user's first spin in the current cooldown
+period. Compute the countdown:
+
+```ts
+const msTillNext = template.max_spins_period_ms! - (Date.now() - r.first_spin_in_period!);
+```
+
+Show "Available in HH:MM:SS" countdown on the disabled Play CTA.
+
+## Jackpot wins in batches
+
+When a result has `jackpot_amount` set, the user won a jackpot on
+that specific spin. Drain the template's `jackpot_current` in the
+UI (the next `getMiniGames` push will confirm the reset).
+
+For multi-jackpot wins in a single batch (rare but possible), sum
+the amounts visually.
+
+## Animations / transitions
+
+Sequential animation pattern (most common):
+
+  1. Disable the Play CTA, show loading state.
+  2. For each result in order:
+     - Trigger the game-type animation (wheel spin, scratch
+       reveal, lootbox open, etc.).
+     - Sync the final position / reveal to the result's prize.
+     - Show a brief prize callout (~500 ms) between spins.
+  3. After the last spin, show a summary modal with total wins.
+
+The default Smartico UI uses this pattern for lootboxes; wheel /
+plinko / coin flip typically animate one at a time.
+
+## Mobile vs desktop
+
+- **Sequential animation**: identical on both, just smaller canvas
+  on mobile.
+- **Summary modal**: desktop centered; mobile full-screen sheet.
+
+## Performance
+
+- Single round-trip per batch — much cheaper than N sequential
+  `playMiniGame` calls (one WS roundtrip vs N).
+- Pre-determine the animation sequence from the result array
+  before starting — don't await each spin's animation completion
+  before deciding the next.