@smartico/public-api 0.0.380 → 0.0.382

package/docs/ui/avatars/UIGuide_setAvatar.md

@@ -0,0 +1,118 @@
+# UI Guide — `setAvatar`
+
+## Overview
+- Activates the chosen avatar as the user's profile avatar.
+- Confirmation-style mutation — user picks an avatar in
+  [`getAvatarsList`](../../api/classes/WSAPIAvatars.md#getavatarslist)
+  (or a variant from
+  [`getAvatarsCustomized`](../../api/classes/WSAPIAvatars.md#getavatarscustomized)),
+  then taps "Apply".
+- Server validates ownership — locked avatars are rejected.
+- The SDK clears both the catalog and the customized-variant caches on
+  return; re-call those methods to surface the new `is_in_use` state.
+
+## Loading state
+
+User taps "Apply" → the button enters an in-flight state (spinner +
+disabled). The default Smartico UI keeps the picker open during the
+call and closes it after the response lands.
+
+```ts
+const [applying, setApplying] = useState(false);
+
+const onApply = async (avatar: TAvatarDefinition) => {
+  if (applying) return;
+  setApplying(true);
+  const r = await window._smartico.api.setAvatar({
+    avatar_url:     avatar.avatar_url,
+    avatar_real_id: avatar.avatar_real_id,
+  });
+  setApplying(false);
+  handleResult(r);
+};
+```
+
+## Idempotency guard
+
+The SDK does NOT prevent double-clicks. Guard the call site as above.
+Re-applying the same avatar is safe server-side (returns `err_code: 0`,
+no double side-effects), but the redundant roundtrip wastes the user's
+time.
+
+## Action button decision matrix
+
+UI behavior per `err_code`:
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Close picker; refresh header avatar; show brief "Avatar updated" confirmation (optional). |
+| `1` (not in catalog) | Refresh catalog (operator may have removed the avatar); show "Avatar no longer available". |
+| `2` (inactive) | Show "This avatar is no longer available"; refresh catalog. |
+| `3` (outside time window) | Show "Available on {active_from_date} – {active_till_date}". |
+| `4` (not owned) | Show unlock requirement / "Earn this avatar first" — possible if the catalog was stale. Refresh and re-render lock states. |
+| Other non-zero | Show generic error toast. Surface `err_message` if present. Allow retry. |
+
+The default Smartico UI shows a hardcoded "Failed to apply avatar" toast
+on any non-zero code without branching. Custom UIs should branch on the
+code and prefer `err_message` when present.
+
+## Refresh after success
+
+- The SDK auto-clears the
+  [`getAvatarsList`](../../api/classes/WSAPIAvatars.md#getavatarslist)
+  and
+  [`getAvatarsCustomized`](../../api/classes/WSAPIAvatars.md#getavatarscustomized)
+  caches.
+- The user's stored avatar updates server-side; the next call to
+  [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)
+  reflects the new `avatar_url`.
+- **No push to other open sessions.** A second device / tab the user is
+  logged in on will not see the change until it next calls
+  `getUserProfile()` or re-identifies. If you maintain a persistent
+  header avatar across tabs, plan a periodic refresh.
+
+## Selecting the right `avatar_url`
+
+| Source | Pass as `avatar_url` |
+|---|---|
+| Catalog avatar (from `getAvatarsList`) | `avatar.avatar_url` |
+| AI variant (from `getAvatarsCustomized`) | `variant.url` |
+
+For both, pass the base `avatar_real_id` — for an AI variant, that is
+the `avatar_real_id` of the base avatar the variant was derived from
+(it's already on the `TAvatarCustomized` record).
+
+## Animations / transitions
+
+Success sequence (default Smartico UI):
+
+1. Apply tap → spinner replaces button label.
+2. On `err_code === 0` → picker closes, header avatar fades to new
+   image.
+3. Optional: brief toast "Avatar updated" auto-dismissing after ~2 s.
+
+Failure sequence:
+
+1. Apply tap → spinner replaces button label.
+2. On non-zero `err_code` → spinner clears; error toast shown; picker
+   remains open so the user can pick a different avatar.
+
+## Mobile vs desktop
+
+- **Picker**: full-screen sheet on mobile; centered modal on desktop.
+- **Apply button**: bottom bar on mobile; bottom-right of modal on
+  desktop.
+- **Toast**: bottom-center on mobile; top-right on desktop.
+
+## Empty / no-selection state
+
+The "Apply" button should be disabled until the user selects an avatar.
+While selected avatar is the user's current one, the button label
+becomes "In Use" and stays disabled.
+
+## Performance
+
+- Single round-trip.
+- No optimistic update — wait for `err_code === 0` before flipping the
+  header avatar. Locked-avatar rejection is real and would otherwise
+  produce a visible flicker.

package/docs/ui/bonuses/UIGuide_claimBonus.md

@@ -0,0 +1,144 @@
+# UI Guide — `claimBonus`
+
+## Overview
+- Action-focused mutation. The user is on the bonuses screen, the
+  CTA is "Claim" on a pending bonus tile, and they click it.
+- Success (`err_code === 0`) means the operator's integration has
+  been called to credit the bonus to the player's account. The
+  status flips to `REDEEMED` and the bonuses list auto-refreshes
+  via [`getBonuses`](../../api/classes/WSAPIBonuses.md#getbonuses)'s
+  `onUpdate`.
+- Latency: typically 300 ms – 2 s — the server calls the operator's
+  bonus API synchronously inside the claim handler, so slow
+  operator endpoints translate to slow claim responses.
+- Balance updates do NOT arrive in the claim response — the
+  operator credits the player externally and the change surfaces
+  separately (typically via the SDK's user-properties channel).
+
+## Loading state
+
+- **Trigger**: set an in-flight flag (`claiming = true`) immediately
+  on click, BEFORE the call.
+- **Visual**: replace the button label with animated dots / spinner.
+  Disable the button. Keep the claim modal open during the call.
+- **Reset**: clear the flag on response — success or error.
+
+Latency can reach 1–2 s for slow operator integrations. Use a
+clearly-visible loading state (dots ≥ 3 frames, button width
+preserved to prevent layout jump).
+
+## Idempotency UI guard
+
+The SDK does NOT prevent double-clicks. Two simultaneous calls
+both reach the server. The first succeeds; the second returns
+`err_code = -1` (bonus already claimed). Guard the call site:
+
+```ts
+const [claiming, setClaiming] = useState(false);
+
+const onClaim = async () => {
+  if (claiming) return;                          // in-flight guard
+  if (!bonus.is_redeemable) return;              // not claimable
+  setClaiming(true);
+  const r = await window._smartico.api.claimBonus(bonus.bonus_id);
+  setClaiming(false);
+  handleResponse(r);
+};
+```
+
+Treat `err_code === -1` (already claimed) as **idempotent success**
+in the UI — close the modal, show the success toast, let the
+auto-refresh land. Don't show an error.
+
+## Action button decision matrix
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Close the claim modal · Show a success toast (e.g. "Bonus claimed!") · The bonuses list auto-refreshes via `onUpdate`; the bonus moves from Pending to Redeemed tab on the next render — DON'T manually re-fetch. Balance credit arrives separately through the operator's integration. |
+| `-1` (not claimable / already claimed) | Same as success — treat as idempotent. Usually means another tab/session already claimed it (or the bonus expired between list fetch and click). |
+| `1` (generic server error) | Show a generic error toast. Allow retry — the bonus typically lands in `REDEEM_FAILED` and remains claimable. |
+| `9999` (uncaught exception) | Same as `1` — generic error toast, retry allowed. |
+| Other non-zero | Show a generic error toast with `err_message` if present. Allow retry. |
+
+The bonus's `bonus_status_id` after a failed claim is typically
+`REDEEM_FAILED (4)`. The default Smartico UI treats `REDEEM_FAILED`
+identically to `COUPON_ISSUED` — the user sees a normal Claim
+button on their next visit and can retry without any "previously
+failed" indicator.
+
+## `success` field — ignore it
+
+The wire response does NOT consistently carry a `success` boolean.
+The `TClaimBonusResult.success?: boolean` field will be `undefined`
+in practice. **Always branch on `err_code === 0`** for the success
+check, not on the `success` field.
+
+## Acknowledge message — pre-click
+
+`label_bonus_template_meta_map.acknowledge` is the operator-supplied
+text shown in the claim modal (wagering terms, expiry notice, etc.).
+It is **template-level and static** — shown regardless of whether
+the user has clicked Claim yet, and regardless of whether the
+claim eventually succeeds. Render it always in the modal body when
+present.
+
+## Optimistic update
+
+**Do NOT optimistically flip `bonus_status_id` to `REDEEMED`** before
+the response. The server can fail (operator integration timeout,
+business-rule rejection), and the failure state needs to surface as
+a real error. Keep the bonus in its prior state until the response
+lands.
+
+The in-flight `claiming` flag provides the visual feedback during
+the wait.
+
+## Refresh after response
+
+The SDK auto-refreshes the bonuses cache on every response (success
+OR error) via the same push that delivers the claim result. The
+`onUpdate` callback registered via `getBonuses({ onUpdate })` fires
+with the refreshed array shortly after — **don't manually call
+`getBonuses()` after a claim response**, the refresh is already
+happening.
+
+The user's balance update (after a successful claim) does NOT come
+through the bonuses channel. The operator's integration credits the
+player externally; balance updates surface via
+[`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)'s
+`props_change` push channel — subscribe there separately if your UI
+shows the balance.
+
+## Animations / transitions
+
+- **Loading dots**: 3-dot bouncing animation on the button while
+  the promise is in flight.
+- **Modal close on success**: animate the modal closure (~150 ms
+  ease-out).
+- **Card cross-tab transition**: when the bonus moves from Pending
+  to Redeemed (detected via diffing the prior + refreshed lists
+  inside `onUpdate`), the default Smartico UI does not animate the
+  move — it relies on the list-level fade-in for the new Redeemed
+  card.
+- **No celebration animation** (no confetti, no sound) — bonus claim
+  uses a plain success toast. Mission and store claims have
+  celebrations; bonuses don't.
+
+## Mobile vs desktop
+
+- **Loading state**: identical (dots animation on the button).
+- **Error surfacing**: desktop typically uses a toast/snackbar;
+  mobile may use a centered modal with a clear "OK" affordance.
+- **Modal style**: desktop centered with backdrop dim; mobile
+  full-screen slide-up sheet.
+
+## Performance
+
+- Single round-trip per click. The handler invokes the operator's
+  bonus API synchronously, so latency depends on the operator's
+  endpoint responsiveness.
+- The refresh after the response (server push → SDK cache write →
+  `onUpdate` fire) adds ~50–100 ms beyond the claim response —
+  fine for UI purposes.
+- Don't poll `getBonuses()` to detect claim completion — the
+  response promise is the authoritative signal.

package/docs/ui/bonuses/UIGuide_getBonuses.md

@@ -0,0 +1,176 @@
+# UI Guide — `getBonuses`
+
+## Overview
+- Returns the user's bonuses (pending claims, redeemed history, and —
+  rarely — internal statuses). Drive the rendering from
+  `bonus_status_id` ({@link BonusStatus}) and `is_redeemable`.
+- The list refreshes automatically only after
+  [`claimBonus`](../../api/classes/WSAPIBonuses.md#claimbonus). Server-
+  awarded bonuses (CRM, mission rewards, store redemptions) do NOT
+  push — poll on the 30 s cache TTL if you need near-live awareness.
+- Loading indicator: skip on cache hit; show a shimmer on cold fetch
+  (typically 100–500 ms).
+
+## List view organization
+
+The default Smartico UI splits bonuses into **two tabs**:
+
+| Tab | Bucket rule | Sort |
+|---|---|---|
+| **Pending** | `bonus_status_id === 2` (`COUPON_ISSUED`) OR `bonus_status_id === 4` (`REDEEM_FAILED`) | `create_date` DESC |
+| **Redeemed** | `bonus_status_id === 3` (`REDEEMED`) | `redeem_date` DESC |
+
+Status values `New (1)`, `COUPON_ISSUE_FAILED (5)`, `EXPIRED (6)` are
+typically filtered out by widget-level operator configuration. If they
+appear, the default UI does not surface them — drop them from your
+render.
+
+**Pending tab auto-hides**: when the Pending bucket is empty, the
+default Smartico UI removes the tab strip entirely and shows only the
+Redeemed list. Restore the tab strip when a fresh pending bonus
+appears (e.g. after a poll-driven refresh).
+
+**Bucketing helper** for custom UIs:
+
+```ts
+function bucket(bonus) {
+  if (bonus.bonus_status_id === 2 || bonus.bonus_status_id === 4) return 'pending';
+  if (bonus.bonus_status_id === 3) return 'redeemed';
+  return null;  // drop internal statuses from the UI
+}
+```
+
+## Bonus card / tile
+
+Fields rendered per tile:
+
+| Field | Source | Notes |
+|---|---|---|
+| Icon | `label_bonus_template_meta_map.image_url` | 1:1 aspect ratio. No SDK-provided fallback — supply a neutral placeholder if missing. |
+| Amount / title | Prefer `bonus_meta_map.uiAmount` (e.g. `"€50"`, `"100 free spins"`); fall back to `label_bonus_template_meta_map.description` | `description` may include HTML; sanitize before injecting. |
+| Date | `create_date` for pending bonuses; `redeem_date` for redeemed bonuses | ISO 8601 UTC; parse and format in user's local time (`new Date(create_date + 'Z')`). |
+| Redirect affordance | Small icon when `label_bonus_template_meta_map.redirect_url` is set | Separate click target from the card itself (don't open the claim modal on icon click). |
+
+**Whole-card click target** behavior depends on the bonus state:
+- Pending + `is_redeemable: true` → opens the claim modal (see "Action
+  button decision matrix").
+- All other states → card is non-interactive (apply a CSS class like
+  `hover-disable` and suppress the click handler).
+
+## Detail / claim modal
+
+When the user clicks a claimable card, open a modal showing:
+
+  1. Bonus icon (`label_bonus_template_meta_map.image_url`) at a
+     larger size.
+  2. Amount / title (same fields as the card).
+  3. Description (`label_bonus_template_meta_map.description`, HTML).
+  4. **Acknowledge message** —
+     `label_bonus_template_meta_map.acknowledge` — operator-supplied
+     text always shown when set (wagering terms, expiry notice,
+     etc.). May include deep-links — pass through the SDK's deep-link
+     handler for safe execution.
+  5. Claim button (see "Action button decision matrix").
+
+The acknowledge message is **template-level static text**, not a
+dynamic success message — it appears regardless of whether the
+claim succeeds.
+
+## Action button decision matrix
+
+Drive the Claim CTA from `bonus_status_id` + `is_redeemable`:
+
+| `bonus_status_id` | `is_redeemable` | UI state |
+|---|---|---|
+| `COUPON_ISSUED` (2) | `true` | Claim button enabled — primary CTA |
+| `REDEEM_FAILED` (4) | `true` | Claim button enabled — "Try again" label is appropriate; the default Smartico UI treats this identically to first-time claim |
+| `COUPON_ISSUED` / `REDEEM_FAILED` | `false` | Card is informational only; no Claim button (auto-redeemed integration) |
+| `REDEEMED` (3) | (irrelevant) | History row; no Claim button; show `redeem_date` |
+| `New` / `COUPON_ISSUE_FAILED` / `EXPIRED` | — | Drop from UI |
+
+Clicking the Claim button invokes
+[`claimBonus`](../../api/classes/WSAPIBonuses.md#claimbonus). See its
+own UI guide for the in-flight + per-error-code matrix.
+
+## Image / asset specs
+
+| Field | Aspect ratio | Notes |
+|---|---|---|
+| `label_bonus_template_meta_map.image_url` | 1:1 (square) | Operator-supplied; recommended ~256×256 px. Fallback: render a neutral bonus icon if missing. |
+
+## Status-specific visual treatments
+
+- **Pending (`COUPON_ISSUED` / `REDEEM_FAILED`)**: full-color card,
+  pointer cursor, clickable.
+- **Non-redeemable pending** (`is_redeemable: false`): identical
+  visual but `hover-disable` CSS class, no click handler.
+- **Redeemed**: same visual; appears in the Redeemed tab only; show
+  the redemption date.
+- **No status-specific colors / badges** in the default Smartico UI
+  — branding for "successfully redeemed" lives only in tab placement,
+  not in the card chrome.
+
+`REDEEM_FAILED` is visually identical to `COUPON_ISSUED` from the
+player's perspective. The "failed" state is a server-internal
+distinction that lets the integration record a prior failed attempt
+without losing the bonus. Don't surface "failed" in the UI copy —
+treat it as "claim available".
+
+## `redirect_url` handling
+
+When `label_bonus_template_meta_map.redirect_url` is set, render a
+small redirect icon on the card. Click behavior:
+
+- URL starts with `http` / `https` → open in a new browser tab
+  (`window.open(url, '_blank')`).
+- Anything else → treat as an internal deep-link; pass to the SDK's
+  deep-link handler (`_smartico.dp(url)`).
+
+The redirect click target is **separate from** the card's click
+target. Stop event propagation on the icon click so the claim modal
+does not open simultaneously.
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: render a skeleton grid (3–6 placeholder
+  cards) matching the eventual layout.
+- **Loading (cache hit)**: do not render a loading state — the
+  promise resolves within a microtask.
+- **Empty list**: `[]` means no bonuses are visible. Show a neutral
+  empty-state illustration with copy like "No bonuses available".
+- **Empty Pending tab (but Redeemed has items)**: per the default
+  Smartico UI, hide the tab strip entirely and show only the
+  Redeemed list. Reverse when a poll-driven refresh restores
+  pending bonuses.
+- **Error**: keep the prior list visible if any; show a small
+  non-blocking error banner; retry on the next user-driven action.
+
+## Animations / transitions
+
+- **Card entry**: stagger fade-in (~30 ms per card) on first render.
+- **Card transition on claim success**: the redeemed bonus's card
+  fades out from the Pending tab and the Redeemed tab gains a new
+  card on its next render. The default Smartico UI does not animate
+  the cross-tab move — bonus rendering relies on the standard list
+  refresh.
+- **No celebration animation on claim success** — unlike mission /
+  store claim, bonuses use a plain success toast.
+
+## Mobile vs desktop
+
+- **Grid columns**: desktop typically 2–3 columns; mobile 1
+  (full-width cards).
+- **Tab strip**: identical on both; auto-hidden when Pending is
+  empty.
+- **Detail modal**: desktop centered with backdrop dim; mobile
+  full-screen slide-up.
+
+## Performance
+
+- The 30 s cache deduplicates rapid refetches. A poll loop every
+  5 s effectively translates to one round-trip per 30 s.
+- Diff snapshots between fetches to detect status flips and animate
+  only the affected cards.
+- For very large bonus histories, virtualize the Redeemed tab with
+  `IntersectionObserver` — the default Smartico UI doesn't
+  paginate, so the full list is rendered.

package/docs/ui/gamepick/UIGuide_gamePickGetActiveRound.md

@@ -0,0 +1,99 @@
+# UI Guide — `gamePickGetActiveRound`
+
+## Overview
+- Returns a single round with its events, user selections, scoring rules.
+- Powers the round-detail / prediction-input screen.
+- No cache; no push subscription.
+
+## Detail view layout
+
+Top-to-bottom sections in the default Smartico UI:
+
+1. **Header**: round name + description + status pill (see
+   [`gamePickGetActiveRounds`](../../api/classes/WSAPIGamePick.md#gamepickgetactiverounds)
+   for status mapping).
+2. **Timer / deadline**: countdown to `last_bet_date` ("Bets close in 2h 15m").
+3. **Score recap (if scored)**: `user_score`, full/partial/lost counts.
+4. **Event list**: one row per event in `events[]`.
+
+## Event row layout
+
+Each event row carries:
+
+| Field | Source | Notes |
+|---|---|---|
+| Teams / question | `event_meta.team1_name`, `event_meta.team2_name` (MatchX) or `event_meta.text` (Quiz) | Heading |
+| Team images | `event_meta.team1_img`, `event_meta.team2_img` | 32×32 px (1:1) |
+| Match date | `match_date` | "Sat 25 May · 16:00" |
+| Sport | `event_meta.sport` | Small chip |
+| Odds | `odds_details` | Optional display |
+| User selection input | based on `market_type_id` | Score pickers (MatchX) / radio (Quiz) |
+| Resolution badge | `resolution_type_id` (`GamePickResolutionType`) | Only after resolution |
+| `is_open_for_bets` | boolean | Disable input when false |
+
+## Prediction input by `market_type_id`
+
+| Market | Input type |
+|---|---|
+| MatchX Goals / Winner | Two numeric pickers (team1 score / team2 score) |
+| Quiz 1×2 | Three buttons (1 / X / 2) |
+| Quiz Yes / No | Two buttons (Yes / No) |
+| Quiz custom | Operator-defined buttons |
+
+## Action button decision matrix
+
+Bottom CTA per round state:
+
+| State | CTA |
+|---|---|
+| `is_active_now && has_open_for_bet_events && !user_placed_bet` | "Submit predictions" (primary) |
+| `is_active_now && has_open_for_bet_events && user_placed_bet` (and edits made) | "Update predictions" (primary) |
+| `is_active_now && user_placed_bet` (no pending changes) | Disabled "Predictions submitted" |
+| `!has_open_for_bet_events` | Hidden / "View only" message |
+| `is_resolved` | "View results" — links to history |
+
+## Resolution badges (`GamePickResolutionType`)
+
+| Value | Badge |
+|---|---|
+| `None` (0) | No badge (event not yet resolved) |
+| `Lost` (2) | Red X icon |
+| `PartialWin` (3) | Amber half-star |
+| `FullWin` (4) | Green checkmark |
+
+## Edits and `allow_edit_answers`
+
+When the round is open and an event's `is_open_for_bets` is true, the user
+can edit predictions for that event. The `allow_edit_answers` flag on the
+round controls whether edits are accepted; the server enforces this and
+returns `errCode: 3` (no-op) if submits happen after the deadline.
+
+## Error states
+
+| `errCode` | Treatment |
+|---|---|
+| `4` (round / event not found) | Refresh active rounds and bounce back to lobby |
+| `100002` (template not found) | Bounce back to lobby |
+| `100000` (auth) | Re-init session |
+
+## Refresh
+
+- No SDK cache.
+- Re-call after a submit to surface the persisted predictions and updated
+  state.
+- Poll every 30–60 s while the user is on the screen if event resolution
+  updates matter.
+
+## Mobile vs desktop
+
+- **Mobile**: event rows stack full-width with score pickers below the
+  teams.
+- **Desktop**: 2-column event grid; score pickers inline with teams.
+
+## Performance
+
+- Single round-trip. The full event list ships in one payload.
+- For lobby views with many rounds, prefer
+  [`gamePickGetGameInfo`](../../api/classes/WSAPIGamePick.md#gamepickgetgameinfo)
+  for a metadata-only round list and only call this method when the user
+  opens a specific round.

package/docs/ui/gamepick/UIGuide_gamePickGetActiveRounds.md

@@ -0,0 +1,76 @@
+# UI Guide — `gamePickGetActiveRounds`
+
+## Overview
+- Returns every open round for a MatchX or Quiz game template, with full
+  event lists and the user's selections per event.
+- Powers the rounds-lobby screen.
+- No SDK cache; every call is a live HTTP roundtrip to the Game Pick games
+  server.
+- No push subscription — poll if you need live status updates.
+
+## List view organization
+
+Single flat list of round cards. The default Smartico UI sorts by `open_date`
+ascending (closest-opening or already-open first). Rounds with status
+`NoEventsDefined` (1) are filtered out server-side and never appear.
+
+## Item card / tile
+
+Fields rendered per round card:
+
+| Field | Source | Notes |
+|---|---|---|
+| Round name | `round_name` | Title |
+| Description | `round_description` | Subtitle (truncated) |
+| Open / close window | `open_date`, `last_bet_date` | "Bets close in 2h 15m" |
+| Event count | `events.length` | "5 matches" / "10 questions" |
+| User progress | `user_placed_bet` | "Predictions submitted" badge or "Make your picks" CTA |
+| Score so far | `user_score` | Visible after resolution |
+| Status pill | `round_status_id` | See mapping below |
+
+## Status pill mapping (`GPRoundStatus`)
+
+| Value | Label / treatment |
+|---|---|
+| `Other` (-1) | Active — green pill "Open" |
+| `NoMoreBetsAllowed` (2) | Amber pill "Bets closed" |
+| `AllEventsResolved_ButNotRound` (3) | Blue pill "Awaiting resolution" |
+| `RoundResolved` (4) | Gray pill "Resolved" |
+
+(Status 1 `NoEventsDefined` never appears here.)
+
+## Click target
+
+Single tap opens the round-detail view (calls
+[`gamePickGetActiveRound`](../../api/classes/WSAPIGamePick.md#gamepickgetactiveround)
+for that round).
+
+## Empty / loading / error states
+
+- **Empty (`errCode: 100003`)**: "No open rounds right now — check back later."
+- **Loading**: skeleton card list (2–3 placeholders).
+- **Error (`errCode: 100002`)**: "Game not found" — likely template ID is
+  wrong; bounce back to the lobby.
+- **Error (`errCode: 100000`)**: "Session expired — please log in again" —
+  hash auth failure.
+
+## Refresh
+
+- No SDK cache.
+- Poll every 30–60 s while the user is on the lobby screen to catch
+  status changes (events going from open to closed).
+- Re-call after any submit ([`gamePickSubmitSelection`](../../api/classes/WSAPIGamePick.md#gamepicksubmitselection)
+  or [`gamePickSubmitSelectionQuiz`](../../api/classes/WSAPIGamePick.md#gamepicksubmitselectionquiz))
+  to reflect the new `user_placed_bet` state on the relevant round card.
+
+## Mobile vs desktop
+
+- **Mobile**: full-width round cards stacked vertically.
+- **Desktop**: 2- or 3-column grid of round cards.
+
+## Performance
+
+- Each call ships the full event list. For lobbies with many rounds, prefer
+  [`gamePickGetGameInfo`](../../api/classes/WSAPIGamePick.md#gamepickgetgameinfo)
+  which returns round metadata only (no events), then call this method only
+  when the user wants to see prediction-able rounds in detail.