@smartico/public-api 0.0.379 → 0.0.381

package/docs/ui/missions/UIGuide_getAchCategories.md

@@ -0,0 +1,17 @@
+# UI Guide — `getAchCategories`
+
+## UI guidance
+- Treat categories as relatively static. It is safe to fetch once on page load and
+  reuse for the lifetime of the view; the SDK's 30 s cache handles short-term re-calls.
+- Sort by `order` ascending before rendering. Items with the same `order` should
+  fall back to `name` or `id` for stable ordering.
+- For tab UIs, generate one tab per category; "All" / "Other" tabs are
+  caller-provided (not returned by the server).
+- For section UIs (mission/badge listing grouped by category), iterate sorted
+  categories and render only those whose filtered item list is non-empty unless
+  you intentionally want empty sections.
+- Loading indicator: skip on cache hit; show a brief shimmer on cold fetch
+  (typically 100–300 ms).
+
+**Visitor mode**: supported. Use `_smartico.vapi(lang).getAchCategories()` to fetch
+categories with `name` translated to the given language without an authenticated user.

package/docs/ui/missions/UIGuide_getBadges.md

@@ -0,0 +1,237 @@
+# UI Guide — `getBadges`
+
+## Overview
+- Badges are completion-tracked achievements that **auto-unlock** when their
+  criteria are met. No opt-in step, no claim step, no recurring cycles.
+- The same `TMissionOrBadge` shape is reused; treat the mission-only fields
+  on a badge object as not-applicable (see method TSDoc for the list).
+- The default Smartico UI renders badges as a **category-grouped grid** —
+  not a flat list and not as status tabs. Each category section shows
+  `completed / total` in its header.
+- No `onUpdate` subscription. Poll on the 30 s cache TTL or re-fetch on a
+  domain event your app already handles (e.g. after a game round, after a
+  bonus claim).
+- Loading indicator: skip on cache hit; show a brief shimmer on cold fetch
+  (typically 100–500 ms).
+
+## List view organization
+
+Group by category (`category_ids`) and resolve display metadata via
+[`getAchCategories`](../../api/classes/WSAPIMissions.md#getachcategories).
+The category list serves both missions and badges — use it directly.
+
+Recommended layout — sectioned grid:
+
+  1. Fetch badges + categories in parallel.
+  2. Sort categories by `order` ascending.
+  3. For each category, filter `badges.filter(b => b.category_ids.includes(cat.id))`.
+  4. Render one collapsible section per non-empty category, with a header
+     showing `<name> (<completed>/<total>)`.
+  5. Items inside a section render as a fixed-cell grid (typically 3–4
+     columns on desktop, 2 on mobile — see "Mobile vs desktop").
+
+Items with `category_ids: []` (uncategorized): the SDK does NOT return a
+synthetic "Other" category. If your UI surfaces uncategorized badges,
+generate that bucket client-side. Many badge UIs simply hide uncategorized
+badges.
+
+A badge can appear in multiple categories — duplicate rendering across
+sections is intentional. Do NOT dedupe; users navigate categories
+independently.
+
+**Sort within a category**: typical priority — `is_completed === true`
+first (most recently completed by `complete_date_ts` DESC), then
+in-progress (by `position` ASC), then not-yet-started (by `position` ASC),
+then expired (by `position` ASC). `position` is the operator-configured
+display order; lower = higher priority.
+
+## Badge card / tile
+
+Fields to render on the card:
+
+- `image` — documented source size 256×256 px. Render at a 1:1 aspect
+  ratio. There is no built-in placeholder for missing images — provide a
+  neutral fallback (e.g. a generic locked-badge silhouette).
+- `name` — the title. Translated server-side.
+- Stage counter — show **`<completed_tasks> / <total_tasks>`** computed
+  from `tasks` (count `t.is_completed === true` over `tasks.length`), NOT
+  a percentage `progress` bar. The default Smartico UI deliberately keeps
+  task descriptions hidden ("surprise mechanics") and shows only the count
+  of stages cleared. The exception: a single-task badge can show just a
+  completion check-mark instead of `1/1`.
+- Availability chip — drive from `badgeTimeLimitState`. See "Status-specific
+  visual treatments" for the per-state visual treatment.
+- `ribbon` — optional tag rendered as a corner badge (`sale`, `hot`, `new`,
+  `vip` or a custom 250×300 px image URL). Render top-right on the card.
+
+Fields NOT on the card (detail-view only): `description`, full task list
+with names, `hint_text` (T&C), category memberships.
+
+**Click target**: whole card opens the detail view. There is no action
+button on the card itself — badges have no opt-in or claim flow.
+
+## Detail view / popup
+
+Top-to-bottom layout:
+
+  1. **Hero image** — `image` rendered at a larger size (typically
+     320×320 px or full-width up to a max). Apply the same status overlay
+     as the card (see "Status-specific visual treatments").
+  2. **Title & availability chip** — `name` + status chip.
+  3. **Description** — `description` HTML.
+  4. **Task list** — render `tasks[].name` as a vertical list, each with
+     a check-mark when `task.is_completed === true`. Do NOT render
+     `tasks[].progress` percentages; the badge UX convention is "stages
+     cleared", not "percent complete". Optionally show stage `points_reward`
+     beside each task name if the brand surfaces task rewards.
+  5. **Reward summary** — `reward` HTML if non-empty.
+  6. **Timing block** — formatted `active_from_ts` / `active_till_ts` or
+     completion date `complete_date_ts`. See "Countdown / timing format".
+  7. **T&C** — `hint_text` if present, in a smaller collapsible
+     "Terms" panel.
+  8. **Related games** — `related_games` array rendered as a horizontal
+     game-tile strip if non-empty. Each tile clicks through to the game
+     using `related_games[i].game_public_meta.link`.
+
+No primary CTA button at the bottom — badges are passive. If the brand
+wants to drive engagement from the popup, surface a `related_games` strip
+or a deep-link CTA derived from the brand's own configuration; the SDK
+itself does not return one for badges.
+
+## Action button decision matrix
+
+Badges have **no action buttons**. They auto-unlock when criteria are met.
+Anything that looks like an action button in a badge view is either:
+
+- A close / back affordance (popup chrome), or
+- A "View related game" link derived from `related_games[i].game_public_meta.link`, or
+- A custom brand-defined CTA the operator wires up externally — the SDK
+  does not return a `cta_action` payload for badges in practice.
+
+Do NOT render opt-in buttons, claim buttons, or anything that mutates
+state. Both surfaces would no-op against badge IDs (no server endpoint
+accepts a badge for opt-in / claim).
+
+## Image / asset specs
+
+| Field | Documented source size | Aspect ratio | Fallback |
+|---|---|---|---|
+| `image` | 256×256 px | 1:1 | Neutral locked-badge silhouette |
+| `ribbon` (custom URL) | 250×300 px | 5:6 portrait | Hide ribbon if URL fails to load |
+| `related_games[i].game_public_meta.image` | per game-catalog spec (1:1) | 1:1 | Hide tile if image missing |
+
+If `image` is missing or fails to load: render the fallback at the same
+size. Do not show a broken-image icon — this UI surface is consumer-facing
+gamification and a broken image undermines the reward fantasy.
+
+## Status-specific visual treatments
+
+Drive from `badgeTimeLimitState` first, then layer completion state on
+top.
+
+| `badgeTimeLimitState` | Card visual | Availability chip text |
+|---|---|---|
+| `BeforeStartDate` (0) — window hasn't started | Grayscale + subtle dim overlay. Lock-icon corner badge if `is_locked === true`. | `"Starts on <date>"` from `active_from_ts` |
+| `AfterStartDateNoProgress` (1) — active, no progress yet, no end date | Full-color, no overlay | No chip (or a neutral `"Available"`) |
+| `AfterStartDateNoProgressAndEndDate` (2) — active, no progress, has end date | Full-color | `"Until <date>"` from `active_till_ts` |
+| `AfterStartDateWithProgressAndEndDate` (3) — active with progress, has end date | Full-color | `"<countdown>"` to `active_till_ts` (see "Countdown / timing format") |
+| `AfterEndDateNotStarted` (4) — expired, never started | Grayscale + dim overlay + slash/X overlay | `"Expired"` |
+| `AfterEndDateWithProgress` (5) — expired with some progress | Grayscale + dim overlay | `"Ended"` (or `"Expired"`) |
+
+On top of the time-window treatment, layer the completion state:
+
+- `is_completed === true` — color-restored card (override grayscale),
+  prominent check-mark corner badge, glow / shine accent. The default
+  Smartico UI shows the most-recently-completed badges first within a
+  category by `complete_date_ts` DESC.
+- `is_completed === false` and at least one `task.is_completed === true` —
+  show the stage counter prominently (e.g. larger font, contrasting color)
+  to signal in-progress.
+- All other cases — neutral card, stage counter at default emphasis.
+
+## Countdown / timing format
+
+Time displayed varies by badge state. Recommended format ("compact"):
+
+- **Time-until-start** (`badgeTimeLimitState === BeforeStartDate`):
+  - More than 7 days away → `"Starts <date>"` (e.g. `"Starts 12 Jun"`)
+  - 1–7 days → `"Starts in <N> days"`
+  - < 24 h → `"Starts in <Hh Mm>"`
+- **Time-until-end** (`AfterStartDateWithProgressAndEndDate`,
+  `AfterStartDateNoProgressAndEndDate`):
+  - > 7 days → `"Until <date>"`
+  - 1–7 days → `"<N> days left"`
+  - 1–24 h → `"<Hh Mm> left"`
+  - < 1 h → `"<Mm Ss> left"`, updated every second
+- **Completed**: `"Completed <relative>"` (e.g. `"Completed 2 days ago"`)
+  from `complete_date_ts`. Tooltip shows full timestamp.
+- **Expired / ended**: just the static label `"Expired"` or `"Ended"`.
+
+Update cadence:
+- > 1 hour away from boundary → refresh once a minute is enough.
+- < 1 hour → refresh once a second.
+- Avoid rendering ticking timers for badges that don't have an `active_till_ts`
+  (most badges) — most badges are open-ended.
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: render a shimmer grid (skeleton cards) matching
+  the eventual grid layout. Show category-section headers if cached, else
+  shimmer the entire view.
+- **Loading (cache hit)**: do not render a loading state. The promise
+  resolves within a microtask.
+- **Empty result**: `[]` from the server means the brand has no badges
+  configured for the user (rare). Render a neutral empty-state illustration
+  with copy like `"No badges yet"`. Do NOT show this state during the
+  cold-fetch shimmer.
+- **Error**: cache the prior result if any and keep rendering it; show a
+  small non-blocking error banner. Retry on the next poll tick. Do not
+  break the page on a single fetch failure.
+
+## Animations / transitions
+
+- **List entry**: cards fade-in on first render. Within a category section,
+  the default Smartico UI staggers the fade by ~30 ms per card.
+- **Category section expand/collapse**: smooth height animation (~200 ms
+  ease-out).
+- **Badge completion celebration**: when `is_completed` flips from `false`
+  to `true` between fetches (your consumer detects this by diffing the
+  prior list), play a celebration animation on the affected card —
+  shine sweep + check-mark scale-in. The default Smartico UI also opens
+  the detail popup automatically on a freshly-completed badge if the
+  user is currently viewing the badge surface; mirror this only if your
+  product surface justifies it.
+- **Stage tick**: when `completed_tasks` increases between fetches without
+  full completion, briefly highlight the stage counter (color flash for
+  ~500 ms) to acknowledge progress.
+
+## Mobile vs desktop
+
+- **Grid columns**: desktop typically 3–4 columns, tablet 2–3, mobile 2.
+  Cards are square (1:1 image aspect ratio drives the layout).
+- **Card density**: mobile cards may hide the ribbon to reduce visual
+  noise; the stage counter remains.
+- **Detail view**: mobile opens as a full-screen modal (slide-up); desktop
+  opens as a centered popup with backdrop dim.
+- **Category sections**: mobile may default-collapse all sections except
+  the first one with non-zero progress; desktop typically renders all
+  sections expanded.
+
+## Performance
+
+- Diff the badge list between fetches to detect completion / stage events
+  for animations. Avoid full re-renders on every poll tick — keyed
+  per-card rendering matters because the celebration animations break
+  if the DOM nodes are recreated.
+- The `image` URLs are CDN-hosted; let the browser cache them. Lazy-load
+  images below the fold; eager-load images in the first visible category.
+- 30 s polling is fine for a small to medium badge catalog (< 200 badges).
+  For very large catalogs, consider polling only when the badges surface
+  is in the viewport (use `IntersectionObserver`) — the SDK doesn't
+  throttle for you.
+
+**Visitor mode: not supported.** Use [`getMissions`](../../api/classes/WSAPIMissions.md#getmissions)
+(visitor mode supported) or [`getAchCategories`](../../api/classes/WSAPIMissions.md#getachcategories)
+(visitor mode supported) if you need achievement data for anonymous users.
+Calling `_smartico.vapi(lang).getBadges()` returns no usable data — visitor
+sessions have no badge-progress path on the server.

package/docs/ui/missions/UIGuide_getMissions.md

@@ -0,0 +1,268 @@
+# UI Guide — `getMissions`
+
+## Overview
+- Register `onUpdate` on first render and treat each invocation as
+  "discard prior list, re-render from this array". Do not merge with
+  the previous list — fields like `progress` are absolute, not deltas.
+- Loading indicator: the first `getMissions()` is a server round-trip
+  (typically 100–500 ms); subsequent calls within the cache window
+  resolve effectively synchronously.
+- Don't poll `getMissions()` to detect opt-in / claim completion. The
+  `onUpdate` callback is the authoritative signal.
+- The SDK returns a flat array; there is no pre-computed status bucket
+  field. Consumers apply the bucketing filter chain below themselves.
+
+## Status bucketing
+Partition the array using this **priority order — first match wins**:
+
+  1. **Missed** — time window passed before completion. Test:
+     `(!is_completed) && ((is_requires_optin && is_opted_in || !is_requires_optin)`
+     ` && time_limit_ms && dt_start && (dt_start + time_limit_ms) < Date.now())`
+     `|| (active_till_ts && active_till_ts < Date.now())`.
+     Sort: `position` ASC.
+  2. **Completed** — `is_completed === true`, OR for missions of type
+     `AchievementStatus.RecurringUponCompletion`,
+     `max_completion_count === completion_count` (cap reached) OR
+     `completion_count > 0` (at least one cycle completed).
+     Sort: `complete_date_ts` DESC (most recent first).
+  3. **Locked** — `is_locked === true`, OR not yet available
+     (`active_from_ts > Date.now()`). Sort: `position` ASC.
+  4. **Available (in-progress)** — none of the above.
+     Sort: `position` ASC.
+
+Each mission belongs to exactly ONE bucket. Many UIs render these as
+status tabs / sections. The `availability_status` field
+([AchievementAvailabilityStatus](../../api/enumerations/AchievementAvailabilityStatus.md)) is authoritative for **timer /
+window state** (which countdown to show, whether the window has
+elapsed) — but it is NOT a substitute for bucketing: distinguishing
+"locked" from "opt-in required" requires reading `is_locked` and
+`is_opted_in` directly. An "Overview" tab curating featured +
+in-progress + a sample locked is a common pattern.
+
+## Mission card / tile (list view)
+
+Fields to render on the card:
+- `image` — documented source size 256×256 px. Render at a 1:1 aspect
+  ratio; CSS `background-image` is conventional. There is no built-in
+  placeholder for missing images — provide a neutral fallback.
+- `name` — the title. Translated server-side. Safe to render as HTML
+  if the consumer sanitizes first.
+- Status chip — derived from the bucket the mission falls into;
+  includes a live countdown for time-limited entries (see "time
+  formatting" below).
+- Description (fallback chain): `description` → `unlock_mission_description`
+  (when `is_locked`) → `tasks[0].name` (when no description and tasks
+  exist).
+- Progress bar — render only when `progress > 0` (the 0–100 integer).
+  Hide for completed recurring missions (`AchievementStatus.RecurringUponCompletion`
+  on the Completed tab) to avoid showing residual percentage from a
+  prior cycle.
+- Reward summary (`reward` HTML) — show only when `progress === 0`.
+  For in-progress missions, the progress percentage replaces the reward.
+- Ribbon overlay (`ribbon` field) — presets `'sale'`, `'hot'`, `'new'`,
+  `'vip'` use built-in styling; a URL means a custom **250×300 px** image.
+  Position: top-left corner overlay.
+- "Claim" button — replaces the progress bar when
+  `is_completed && requires_prize_claim && !prize_claimed_date_ts`.
+- "Featured" marker — alternative to ribbon for operator-marked
+  featured missions.
+
+Fields NOT shown on the card (detail popup only):
+- Full `description` HTML beyond a single line
+- `sub_header`
+- `tasks[]` (except as description fallback)
+- `hint_text` (T&C)
+- `related_games`
+- Opt-in / CTA action buttons (the status chip alone communicates
+  "opt-in required" on cards; the actual button lives in the popup)
+
+Click target: the **whole card** opens the detail popup. The Claim
+button (when present) is the only sub-element with its own handler;
+it must `event.stopPropagation()` so the popup doesn't also open.
+
+## Mission detail popup
+
+Top-to-bottom structure (omit sections whose source field is empty):
+  1. Close button.
+  2. Ribbon overlay (same as card).
+  3. Title (`name`).
+  4. Sub-header (`sub_header`).
+  5. Status chip — typically without countdown (use the dedicated
+     time-remaining block below).
+  6. Image (`image`) — render larger than the card variant.
+  7. Lock icon overlay on the image when `is_locked === true`.
+  8. Time-remaining block — "Available again in" countdown for
+     recurring waiting; "Starts on" for `active_from_ts > now`;
+     "Expired on" for missed; countdown for in-window.
+  9. Full `description` (HTML).
+  10. Action button — see the decision matrix below.
+  11. Hint / T&C — `hint_text` surfaced as an info-icon tooltip
+      (tap to expand). Not inline.
+  12. Task list — only when `tasks.length > 1` (single-task missions
+      use the task name as description fallback on the card; the
+      list is redundant). Each task row: completion indicator
+      (checkbox/circle) + `task.name`. Append "N / M" using
+      `execution_count_actual / execution_count_expected` when the
+      operator has enabled count display. Show a points stamp for
+      tasks with `points_reward > 0`.
+  13. Progress bar (conditional, same rule as card).
+  14. Reward block (`reward`).
+  15. Related games — only games where `game_public_meta.enabled === true`.
+      Render as a horizontal carousel; show navigation arrows when
+      5+ games on desktop, 4+ on mobile. Thumbnails are 1:1 aspect
+      ratio; tap a thumbnail to launch the underlying game.
+  16. Unlock description (`unlock_mission_description`) at the
+      bottom when `is_locked`.
+
+## Action button decision matrix
+
+Apply in priority order; **first match wins**:
+
+  1. `is_locked === true` → **no action button**. Show the unlock
+     description and a lock-icon overlay on the image.
+  2. `is_completed && requires_prize_claim && !prize_claimed_date_ts`
+     AND `prize_claim_expiration_date >= Date.now()` (claimable) →
+     **"Claim" button**. Use `claim_button_title` as the label if set,
+     otherwise a localized default. On click: call
+     `requestMissionClaimReward(id, ach_completed_id)`. Optionally
+     animate a celebration overlay after success.
+  3. Same as (2) but claim window expired (`prize_claim_expiration_date < Date.now()`) →
+     render the Claim label as **disabled**; show the formatted expiration
+     date with a "claim expired on" prefix.
+  4. `is_completed` (no claim required, or already claimed) →
+     **no action button**. Show progress / completion state.
+  5. `is_requires_optin && !is_opted_in` (and not locked) →
+     **"Opt In" button**. Disable when:
+       - `active_from_ts > Date.now()` (not yet started),
+       - the mission falls in the Missed bucket,
+       - `active_till_ts && active_till_ts < Date.now()` (expired).
+     While the opt-in request is in flight, show a loading indicator
+     on the button. The SDK does NOT enforce a single in-flight call —
+     guard against double-clicks at the UI layer (set a local
+     `optInLoading` flag on click).
+  6. `cta_text && cta_action` (and none of the above) → **CTA button**
+     labeled with `cta_text`. On click: call
+     `_smartico.dp(cta_action)`. `cta_action` is a deep-link string
+     (e.g. `'dp:deposit'`, `'dp:gf_store'`) — not a URL.
+     Disable when the mission falls in the Missed bucket or is
+     otherwise out of window.
+  7. None of the above → no action button.
+
+Recurring missions:
+- Waiting for next cycle (`next_recurrence_date_ts > Date.now()`) →
+  **no button**; the status chip carries the "Available again in
+  DD:HH:MM:SS" countdown.
+- Cap reached (`max_completion_count === completion_count`) → treated
+  as Completed; no button.
+
+## `claim_button_action` companion action
+
+*(important caveat)*
+
+If `claim_button_action` is set, the consumer's claim handler is
+expected to fire BOTH the claim API call AND the deep-link action
+**at the same time** (concurrently). The deep-link runs synchronously
+on click — it does NOT wait for the claim RPC to succeed. Consequences:
+- If the deep-link navigates away (e.g. opens a casino game), the
+  user may miss the claim loading animation or any error toast.
+- If the claim RPC fails after the navigation has already started,
+  there is no rollback.
+- Treat `claim_button_action` as a *companion navigation*, not a
+  post-claim follow-up. Common pattern:
+  `dispatch claim → _smartico.dp(claim_button_action)` in the same
+  click handler, without `await`-ing the claim.
+- `claim_button_action` accepts both `dp:...` deep-links and full
+  `http(s)://...` URLs (URLs open in a new tab).
+
+## Image / asset specs
+- Mission `image`: documented source size **256×256 px**, 1:1 aspect ratio.
+- Custom ribbon URL: documented source size **250×300 px**.
+- Related-game thumbnails: **1:1 aspect ratio** per `game_public_meta.image`.
+- All assets are typically rendered as CSS `background-image` (no
+  `<img>` element) so dimensions are controlled by the consumer's CSS.
+- No built-in fallback placeholders — consumers should provide one
+  when source fields are empty.
+
+## Status-specific visual treatments
+- **Locked**: lock-icon overlay on the image and a "locked" CSS
+  modifier on the image container. NOT grayscale (grayscale is the
+  convention for locked badges, not locked missions).
+- **Completed**: no tint or strikethrough on the card itself; the
+  status chip carries the completion date.
+- **Missed**: same chip styling as Locked, different label.
+  Missions stay visible in the Missed bucket unless an operator
+  config hides expired missions after N days.
+- **In progress**: default styling.
+- **Opt-in required**: same as in-progress; the status chip alone
+  signals "opt-in required".
+- **Featured**: replace the ribbon (when no `ribbon` is set) with a
+  "featured" modifier; some brands use a gold border / glow.
+- **Claimable** (claim button visible): add a "claimable" modifier
+  to the card root to apply a highlight border or glow drawing
+  attention to the action.
+
+## Time-remaining countdown format
+
+Convention used by the default Smartico UI (consumers should match for
+a consistent feel across Smartico widgets):
+- `≤ 0` → `00:00`
+- `< 1 hour` → `MM:SS`
+- `< 1 day` → `HH:MM:SS`
+- `< 1 month` → `DD:HH:MM:SS`
+- `< 1 year` → `MO:DD:HH:MM:SS`
+- `≥ 1 year` → `YY:MO:DD:HH:MM:SS`
+
+Update the displayed text every 1 second while the mission is in
+progress.
+
+## Empty states
+
+Show a contextual empty-state message per bucket:
+- Completed: "No completed missions yet"
+- Locked: "No locked missions"
+- Others (Available / Missed): "Nothing to show yet"
+
+## Animations / transitions
+- List entry: brief zoom-in or fade-in per card (stagger optional).
+- Popup open: bounce + fade-in; stagger inner elements (title, image,
+  description, actions) for a layered reveal.
+- Progress bar fill: animate the width over ~1 second when progress
+  advances (especially in the popup; cards often render the bar
+  statically).
+- Claim success: hide the Claim button immediately on success and
+  (optionally) overlay a confetti or celebration animation.
+- In-flight buttons (opt-in / claim): show a loading indicator
+  (animated dots, spinner) and disable the trigger element until the
+  response arrives.
+
+## Mobile vs desktop
+- Mobile: single-column vertical scroll.
+- Desktop: multi-column grid. The default Smartico UI alternates a "big"
+  and "small" card variant in a masonry pattern (every 4th in even
+  rows / every 5th in odd rows is "big"). Consumers may use any grid
+  pattern that suits their design.
+- The detail popup is structurally identical on mobile and desktop;
+  only sizing differs.
+
+## Performance
+
+The list is not paginated; the SDK returns the full visible mission
+set in one response. For very large catalogs (50+ missions visible),
+consider client-side virtualization in the consumer UI. The official
+tracker does NOT virtualize.
+
+**Cache TTL**: the SDK caches the response for 30 seconds. The cache
+is invalidated and re-fetched automatically on each of the three
+trigger events above; `onUpdate` fires after the re-fetch completes.
+
+**Visitor mode**: supported, with caveats.
+- The returned list reflects the brand's proxy "visitor" user, not
+  the actual anonymous viewer. Per-user fields (`is_opted_in`,
+  `progress`, `completed_count`) reflect the proxy user's state and
+  are not meaningful for display.
+- `onUpdate` is accepted by the API but NEVER fires in visitor mode —
+  there is no live channel, so push events are not delivered.
+  Visitor-mode consumers should re-poll `getMissions()` periodically
+  if fresh data is needed.
+- Additional server-side caching applies on top of the SDK cache,
+  so visitor-mode data may be a few minutes stale.

package/docs/ui/missions/UIGuide_requestMissionClaimReward.md

@@ -0,0 +1,21 @@
+# UI Guide — `requestMissionClaimReward`
+
+## UI guidance
+- Show a loading indicator while the promise is pending; this is a
+  server round-trip with side effects (DB writes, CRM rules) and may
+  take 200–800ms depending on configured CRM automations.
+- Disable the claim button for the duration of the call. The local
+  `prize_claimed_date_ts` flag won't flip until the auto-refresh fires
+  after the response.
+- Treat `err_code === 0` and `err_code === 40017` identically in the
+  UI: hide the claim button. Don't surface 40017 as an error.
+- For `err_code === 40015` (window expired), show a dedicated message
+  referencing the original `prize_claim_expiration_date`, not a generic
+  error.
+- For `err_code === 40016` (not completed), this should not normally
+  happen if the UI gates on `is_completed === true`. If it does, the
+  local state is stale — auto-refresh will correct it.
+- Do NOT optimistically mark the prize as claimed before the response.
+  Authoritative state comes from the SDK's auto-refresh.
+
+**Visitor mode**: not supported.

package/docs/ui/missions/UIGuide_requestMissionOptIn.md

@@ -0,0 +1,16 @@
+# UI Guide — `requestMissionOptIn`
+
+## UI guidance
+- Show a loading indicator (spinner, dots, button-disable) while the
+  promise is pending; opt-in is a server round-trip and may take
+  100–500ms under normal conditions.
+- Disable the trigger element for the duration of the call to prevent
+  double-clicks. The local `is_opted_in` flag won't flip until the
+  `onUpdate` callback fires post-response.
+- Treat `err_code === 0` and `err_code === 40010` identically in the
+  UI: hide the opt-in button. Don't surface 40010 as an error.
+- For `err_code === 40014` (locked), show the mission's
+  `unlock_mission_description` instead of a generic error.
+- Do NOT optimistically set `is_opted_in = true` before the response.
+  Authoritative refresh comes from the SDK's `onUpdate` invocation,
+  not from local state.

package/docs/ui/raffles/UIGuide_claimRafflePrize.md

@@ -0,0 +1,99 @@
+# UI Guide — `claimRafflePrize`
+
+## Overview
+- Action-focused mutation. The user has a winning row from a raffle
+  draw (visible via
+  [`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun)
+  with `should_claim === true` or via
+  [`getRaffleDrawRunsHistory`](../../api/classes/WSAPIRaffles.md#getraffledrawrunshistory)
+  with `has_unclaimed_prize === true`), and they click Claim.
+- Success (`errorCode === 0`) means the claim is recorded and prize
+  delivery is queued server-side. The actual delivery (wallet
+  credit, free spins, etc.) happens through the operator's
+  integration outside the SDK's response cycle.
+- Latency: typically 200 ms – 1 s for a healthy WebSocket.
+- Balance updates do NOT arrive in this response. Subscribe to
+  [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)'s
+  `props_change` channel to observe credits.
+
+## Result shape note
+
+This method returns `{ errorCode, errorMessage? }` (camelCase
+full-word) — **different** from most other SDK result types that
+use `{ err_code, err_message }` (snake_case). Branch on the
+camelCase keys.
+
+## 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 detail / history view open.
+- **Reset**: clear the flag on response — success or error.
+
+## Idempotency UI guard
+
+The SDK does NOT prevent double-clicks. A second call on the same
+`won_id` returns `errorCode === 1` with `errorMessage` indicating
+the prize has already been claimed. Guard the call site:
+
+```ts
+const [claiming, setClaiming] = useState(false);
+
+const onClaim = async (won_id: number) => {
+  if (claiming) return;                     // in-flight guard
+  setClaiming(true);
+  const r = await window._smartico.api.claimRafflePrize({ won_id });
+  setClaiming(false);
+  handleResponse(r);
+};
+```
+
+Treat `errorCode === 1` with an "already claimed" message as
+**idempotent success** in the UI — the underlying state is what
+the consumer wants.
+
+## Action button decision matrix
+
+| Condition | Action |
+|---|---|
+| `errorCode === 0` (success) | Show a success toast ("Prize claimed!"). The raffles list auto-refreshes via [`getRaffles`](../../api/classes/WSAPIRaffles.md#getraffles)'s `onUpdate`; the winner row's `claimed_date` populates on the next refresh. Don't manually re-fetch. |
+| `errorCode === 1` + `errorMessage` mentions "already claimed" | Treat as success — same UI as above. Surface a brief "Already claimed" toast for clarity if you prefer. |
+| `errorCode === 1` + any other `errorMessage` (control group, mismatch) | Show a generic error toast with the operator message. Allow retry only if the message suggests transient failure. |
+| Other non-zero | Show a generic error toast. Allow retry. |
+
+## Refresh after response
+
+The SDK auto-refreshes the raffles cache on every claim response
+(success OR failure) via the same push that delivers the result.
+The `onUpdate` callback registered via `getRaffles({ onUpdate })`
+fires with the refreshed list. **Don't manually call `getRaffles()`
+after a claim** — the refresh is already happening.
+
+The winner row in the active detail view (`getRaffleDrawRun`) is
+NOT auto-refreshed — call that separately if the detail screen is
+open and you want to see `claimed_date` immediately. The default
+Smartico UI re-fetches the draw detail after a successful claim.
+
+## No celebration animation
+
+Unlike mission / SAW celebrations, the default Smartico UI does
+NOT play a confetti or full-screen animation on raffle claim. The
+winner row updates in-place with the claimed timestamp; a
+success toast is the primary visual feedback. Add a celebration
+in your own UI if your product surface calls for it.
+
+## Mobile vs desktop
+
+- **Error surfacing**: desktop snackbar / toast; mobile centered
+  modal.
+- **Modal style**: desktop centered; mobile full-screen sheet.
+- **Loading state**: identical (dots animation on the button).
+
+## Performance
+
+- Single round-trip per click.
+- Prize delivery through the operator's integration is async
+  and out-of-band — the SDK consumer doesn't observe it directly.
+- Don't poll for delivery confirmation — trust the success
+  response.