@smartico/public-api 0.0.379 → 0.0.381

package/docs/ui/raffles/UIGuide_getRaffleDrawRun.md

@@ -0,0 +1,117 @@
+# UI Guide — `getRaffleDrawRun`
+
+## Overview
+- Powers the **draw detail / winners screen** for a single raffle
+  draw run. Adds paginated `prizes[].winners[]` rows (usernames +
+  avatars) to the same `TRaffleDraw` shape already embedded in
+  [`getRaffles`](../../api/classes/WSAPIRaffles.md#getraffles).
+- One-shot fetch. No cache, no subscription. Re-call to refresh —
+  the default Smartico UI polls on a variable cadence depending on
+  the draw's `current_state`.
+
+## Detail view layout
+
+Top-to-bottom layout:
+
+  1. **Header** — `image_url` / `image_url_mobile` as background.
+  2. **Title + state chip** — `name` + a chip driven by
+     `current_state` (Open / Drawing / Finished).
+  3. **Countdown ticker** — `DD : HH : MM : SS` to `execution_ts`
+     while Open; not rendered during WinnerSelection or after
+     Executed (replaced by drawing animation / winner list).
+  4. **Prize cards** — one per `prizes[]` entry. Each shows
+     `name`, `description`, `image_url`, `prizes_per_run_actual`,
+     and (if `current_state === Executed`) the paginated
+     `winners[]` rows.
+  5. **My tickets** — `my_tickets_count` / `my_last_tickets` for
+     Open draws.
+  6. **Opt-in / claim CTAs** — see the
+     [`requestRaffleOptin`](../../api/classes/WSAPIRaffles.md#requestraffleoptin)
+     and [`claimRafflePrize`](../../api/classes/WSAPIRaffles.md#claimraffleprize)
+     UI guides.
+
+## Winners list (paginated)
+
+When `current_state === Executed`, each prize card carries a
+`winners[]` array (type `TRafflePrizeWinner`). Render as a table:
+
+| Column | Source |
+|---|---|
+| Position | Computed from list order (the server-sorted result places the current user's wins at the top). |
+| Avatar | `winner.avatar_url`. Fallback to a letter avatar when missing. |
+| Username | `winner.username`. Fallback to "Anonymous" if empty. |
+| Ticket | `winner.ticket.ticket_id_string` (use the string form for display). |
+| Claimed | If `winner.claimed_date` is set, show "Claimed"; otherwise show "Pending" (or a Claim CTA if `should_claim === true` and the row matches the current user). |
+
+**Pagination** via `winners_from` / `winners_to`:
+
+- Default window per call: `0 – 20`.
+- Server cap per call: 50 rows. Passing a larger window silently
+  truncates.
+- Total count: `winners_total` on the returned `TRaffleDraw`.
+- The default Smartico UI uses page size 7 internally with a
+  custom pagination component — your UI can choose any size up to
+  50.
+
+For load-more pagination: advance `winners_from` by the prior page
+size on each subsequent call; reuse the same response transform.
+
+## Refresh / polling
+
+`getRaffleDrawRun` has no cache and no push refresh. Poll manually
+when the consumer is viewing a live draw. Recommended cadence
+keyed to `current_state` + remaining time:
+
+| State / Time | Poll interval |
+|---|---|
+| `WinnerSelection` (drawing) | 3 s |
+| `Open`, `< 5 minutes` to execution | 10 s |
+| `Open`, `> 5 minutes` to execution | 30 s |
+| `Executed` | No polling needed (state is terminal) |
+
+Stop polling when the detail view unmounts.
+
+## Image / asset specs
+
+Inherits from [`getRaffles`](./UIGuide_getRaffles.md#image--asset-specs):
+
+- Draw promo: 365×175 px (desktop), 300×145 px (mobile)
+- Background image: 900×85 px (desktop), 1328×240 px (mobile)
+- Prize image: 256×256 px (1:1 square)
+- Avatar: serve via CDN; letter-avatar fallback when empty
+
+## Empty / loading / error states
+
+- **Loading**: render the modal frame + countdown immediately
+  (driven by the caller-side `TRaffleDraw` from `getRaffles`);
+  show a winners-list skeleton while the call is in flight.
+- **`winners[]` empty** (Executed draw with no winners): render
+  "No winners yet" placeholder. Rare — the server should have
+  selected at least one winner per `prizes_per_run_actual`.
+- **Error**: keep the prior snapshot if any; show a non-blocking
+  error banner; retry on next poll tick.
+
+## Animations / transitions
+
+- **WinnerSelection**: full-screen Lottie drawing animation; the
+  winners list area is hidden until state transitions to Executed.
+- **Winners-list page change**: cross-fade rows on pagination.
+- **No confetti / celebration animation** on the user's win row —
+  surface a "You won!" pill on rows where `should_claim` is true
+  for the current user.
+
+## Mobile vs desktop
+
+- **Modal style**: desktop centered with backdrop dim; mobile
+  full-screen slide-up sheet.
+- **Image source**: desktop fields vs `*_mobile` fields.
+- **Winners-list layout**: desktop 4 columns; mobile may collapse
+  the position column or compact the row.
+
+## Performance
+
+- Each call is a fresh network round-trip. During live drawing
+  (3 s polling), this is the active surface; `getRaffles` is not
+  polled in parallel.
+- Pagination is server-side — don't over-fetch by passing a large
+  window; reuse smaller windows.

package/docs/ui/raffles/UIGuide_getRaffleDrawRunsHistory.md

@@ -0,0 +1,92 @@
+# UI Guide — `getRaffleDrawRunsHistory`
+
+## Overview
+- Powers a **draw-history modal / page** showing past-executed runs
+  for a raffle (optionally scoped to a single recurring draw
+  schedule).
+- Use to surface unclaimed-prize CTAs across the user's history,
+  let the user revisit completed draws, or build a "my wins"
+  surface.
+- One-shot fetch, no cache. Re-call to refresh — typically only
+  needed after a new execution lands or after a
+  [`claimRafflePrize`](../../api/classes/WSAPIRaffles.md#claimraffleprize)
+  call resolves.
+
+## List view organization
+
+Server-sorted by `execution_ts` DESC (newest first). No client-side
+sort required.
+
+If `props.draw_id` is omitted, the list interleaves history across
+all draws of the raffle. The default Smartico UI shows them in
+their server order — no per-draw grouping. To group by draw, key on
+`row.id` (the schedule_id) client-side.
+
+If `props.draw_id` is set, the list scopes to one draw's recurring
+history.
+
+## Item row
+
+Fields rendered per row:
+
+| Field | Source | Notes |
+|---|---|---|
+| Image | `image_url` (or `image_url_mobile` on mobile); fallback to `icon_url` | Same specs as in `getRaffles` UI guide. |
+| Name | `name` | |
+| Description | `description` | Optional; the default UI may omit it on dense lists. |
+| Grand badge | If `is_grand === true`, render a "Grand" pill | |
+| Scheduled date | `execution_ts` formatted as user-local date/time | |
+| Actual date | `actual_execution_ts` — typically same as scheduled, but may differ slightly on recovery paths | |
+| User won? | If `is_winner === true`, surface a "You won!" pill | |
+| Claim CTA | If `has_unclaimed_prize === true`, show a "Claim" button that opens the prize detail via [`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun) | |
+
+Row click target: opens the executed draw's detail view (winner
+list) by calling `getRaffleDrawRun({ raffle_id, run_id })`.
+
+## Claim CTA on history rows
+
+When `row.has_unclaimed_prize === true`, surface a Claim button.
+Clicking it should:
+
+1. Fetch the run detail via
+   [`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun)
+   to locate the user's winning row(s).
+2. Pass each winner row's `raf_won_id` to
+   [`claimRafflePrize`](../../api/classes/WSAPIRaffles.md#claimraffleprize).
+
+The default Smartico UI renders the Claim button inline on the
+history row and opens a confirmation flow when clicked.
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: render a skeleton list (3–5
+  placeholder rows) sized to the eventual layout.
+- **Empty result**: `[]` means no executed runs yet. Render a
+  neutral empty-state ("No history yet").
+- **Error**: keep prior state if any; show a non-blocking error
+  banner; retry on next user-driven action.
+
+## Refresh
+
+No subscription, no cache, no push. Call manually:
+
+- After a `claimRafflePrize` resolves (to refresh
+  `has_unclaimed_prize`).
+- After a new run executes on the server side (the user observes
+  the new history row).
+- On a periodic poll if your UI wants to show new executions
+  promptly — typically not necessary for history surfaces.
+
+## Mobile vs desktop
+
+- **Image source**: `image_url_mobile` / `background_image_url_mobile`
+  on mobile.
+- **Row density**: mobile may collapse description and date columns
+  to save horizontal space.
+
+## Performance
+
+- Each call is a fresh network round-trip. Scope with `draw_id` when
+  possible to keep response size manageable.
+- Don't poll the history surface in real time — re-fetch
+  on user-initiated actions only.

package/docs/ui/raffles/UIGuide_getRaffleWonPrizes.md

@@ -0,0 +1,120 @@
+# UI Guide — `getRaffleWonPrizes`
+
+## Overview
+- Powers a **"my prizes" screen** for a single raffle — the flat list of
+  every prize the current user has won across all of that raffle's draws,
+  newest-won first.
+- One-shot, paginated fetch. No cache, no subscription. Re-call to refresh
+  (e.g. after a [`claimRafflePrize`](../../api/classes/WSAPIRaffles.md#claimraffleprize)).
+- Each row already carries `public_meta.name` + `public_meta.image_url`, so
+  you can render full prize cards without a follow-up
+  [`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun) call.
+
+## List view organization
+
+- Single flat list (no per-draw grouping), ordered newest-win first.
+- There is **no** server-side "unclaimed first" ordering. If your design
+  surfaces actionable prizes at the top, sort client-side by
+  `requires_claim && !claimed_date`, then keep the server order within each
+  group.
+- Drive "load more" off `total` (the full win count across all draws), not
+  off the page length:
+
+```ts
+const hasMore = page.offset + page.won_prizes.length < page.total;
+console.log('[smartico] more pages?', hasMore);
+```
+
+## Item card / tile
+
+One card per `won_prizes[]` row:
+
+| Element | Source | Notes |
+|---|---|---|
+| Prize image | `public_meta.name` → `public_meta.image_url` | Square artwork; the default Smartico UI renders it as a circular icon. |
+| Prize name | `public_meta.name` | Localised. Truncate long names (~30 chars) with an ellipsis. |
+| Claimed / Claim CTA | `requires_claim` + `claimed_date` | See the action matrix below. |
+| Won-by attribution | `user.public_username` / `user.avatar_id` | The list belongs to one user; usually shown once in the header, not per card. |
+
+## Action button decision matrix
+
+Per row:
+
+| `requires_claim` | `claimed_date` | Render |
+|---|---|---|
+| `false` | (any) | No CTA — prize was auto-delivered. Optionally show a "Delivered" tag. |
+| `true` | `null` | **Claim** button. On click call `claimRafflePrize({ won_id: prize.raf_won_id })` — `raf_won_id` IS the `won_id`. |
+| `true` | epoch ms | No CTA — show a "Claimed" tag (optionally with the claimed date). |
+
+```ts
+const canClaim = prize.requires_claim && !prize.claimed_date;
+if (canClaim) {
+  console.log('[smartico] show Claim — on click: claimRafflePrize({ won_id:', prize.raf_won_id, '})');
+}
+```
+
+Guard the Claim button against double-clicks (set an in-flight flag on click).
+A second claim of an already-claimed prize is rejected server-side. After a
+successful claim, re-call `getRaffleWonPrizes` to pick up the new
+`claimed_date` (this method has no `onUpdate`).
+
+## User attribution (avatar + username)
+
+The `user` object describes whose prizes these are.
+
+- **Null-check `user` first** — it is `null` when `won_prizes` is empty.
+- **Avatar**: use `user.avatar_id`. If it already starts with `http`, use it
+  directly as the `<img src>`. Otherwise it is an avatar token — prepend the
+  widget's configured avatar domain (`{avatarDomain}/avatar/{avatar_id}`).
+  `user.avatar_url` is always `null`; ignore it. `user.avatar_real_id`
+  identifies the avatar definition internally and is not used for rendering.
+- **Username**: `user.public_username` is server-masked for privacy (e.g.
+  `"32:r*****"`). Render it verbatim. For the current user, show a localised
+  "You" label instead of the masked string.
+
+## Image / asset specs
+
+- Prize image (`public_meta.image_url`): square (1:1) CDN artwork. The default
+  Smartico UI renders it at 40×40 px with `border-radius: 50%`.
+- Provide a letter/placeholder fallback when `image_url` is empty.
+
+## Empty / loading / error states
+
+- **Loading**: show a card skeleton grid while the call is in flight.
+- **Empty** (`errCode === 0` and `won_prizes.length === 0`): render an empty
+  state ("No prizes won yet"). Note this is *also* the response when the user
+  is not eligible to see the raffle — the two are indistinguishable, so keep
+  the copy neutral.
+- **Error** (`errCode !== 0`): keep any prior snapshot; show a non-blocking
+  error banner with a retry. `errCode` is `1` for all server errors —
+  surface `errMsg` if present.
+
+## Refresh / polling
+
+- One-shot promise; no client cache; no push refresh.
+- Re-call on screen open, on explicit "load more", and after a successful
+  `claimRafflePrize`.
+- **Do not poll on a timer** — the server rate-limits this call (~30/min, with
+  a ~5 s minimum gap between calls). Tight polling will start failing.
+
+## Pagination
+
+- `offset` / `limit` page the rows; the SDK defaults to `0` / `20`.
+- The server does **not** clamp `limit` — pass an explicit, sane page size.
+- An `offset` past the end returns an empty page with the real `total` and
+  `errCode 0` (not an error).
+- For "load more": advance `offset` by your page size each call.
+
+## Mobile vs desktop
+
+- Desktop: multi-column card grid. Mobile: single-column list or compact
+  2-column grid.
+- The response shape is identical across viewports; only layout density
+  differs.
+
+## Performance
+
+- Each call is a fresh network round-trip. Fetch one page at a time and append
+  on "load more" rather than pre-fetching all pages.
+- The server caches responses briefly, so a quick re-open is cheap — but the
+  rate limit still applies; debounce rapid re-fetches.

package/docs/ui/raffles/UIGuide_getRaffles.md

@@ -0,0 +1,175 @@
+# UI Guide — `getRaffles`
+
+## Overview
+- Returns the user's visible raffles, each carrying an embedded
+  `draws[]` array with full per-draw state. Use as the source-of-truth
+  for the raffles lobby + draw cards.
+- The list refreshes automatically after
+  [`claimRafflePrize`](../../api/classes/WSAPIRaffles.md#claimraffleprize)
+  or
+  [`requestRaffleOptin`](../../api/classes/WSAPIRaffles.md#requestraffleoptin)
+  resolves. Server-side draw executions invalidate the SDK cache too.
+- Winner detail (usernames, avatars) requires a follow-up call to
+  [`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun)
+  — the embedded `draws[]` carry only pagination metadata.
+
+## List view organization
+
+The default Smartico UI renders raffles as a vertical list with each
+raffle expanding to show its draws. There are no top-level tabs.
+
+Per-raffle, draws are bucketed within the detail panel:
+
+  1. **Active / Upcoming** — `draws.filter(d => d.current_state !== 3)`
+     (1 = Open, 2 = WinnerSelection); sort by `execution_ts` ASC.
+  2. **Executed** — `draws.filter(d => d.current_state === 3)`;
+     rendered after the active draws.
+
+## Ticket-cap banner
+
+Drive from `TRaffle.ticket_cap_visualization` (enum):
+
+| Value | Banner |
+|---|---|
+| `Empty` (0) | No banner. |
+| `Counter` (1) | "X tickets remaining" where X = `max_tickets_count - current_tickets_count`. Format large numbers with locale separators. |
+| `Message` (2) | "All tickets have been distributed" (when 0 remaining). |
+
+## Raffle card (top-level)
+
+Fields rendered on each raffle row:
+
+- `image_url` (890×193 px desktop) / `image_url_mobile` (300×142 px).
+- `name`, `description`.
+- `start_date` / `end_date` — formatted as user-local dates.
+- Total tickets banner (see above).
+- Draw count or active-draw summary.
+
+`custom_section_id` lets the consumer place the raffle into an
+operator-defined custom section. `custom_data` is operator-defined
+JSON / string for custom UI extensions.
+
+## Draw card (per-raffle children)
+
+Fields rendered on each `draws[i]`:
+
+| Field | Notes |
+|---|---|
+| Card image | `background_image_url` (900×85 px desktop) / `background_image_url_mobile` (1328×240 px). Falls back to `icon_url` (256×256). |
+| Title | `name`. |
+| Description | `description`. |
+| Grand badge | If `is_grand === true`, render a "Grand draw" pill. |
+| Countdown | To `execution_ts`. See "Countdown / timing format". |
+| State chip | Drive from `current_state` ({@link RaffleDrawInstanceState}): Open / Drawing / Finished. |
+| My-tickets | `my_tickets_count` if > 0. |
+| Last tickets preview | `my_last_tickets[]` (capped at ~5; newest first). Note the SDK field is spelled `ticekt_id` (typo). |
+| Total tickets | `total_tickets_count`. |
+| Prize summary | Top-priority prize from `prizes[]`. |
+| Opt-in / Opted-in chip | See "Action button decision matrix". |
+
+The draw card click target opens the draw detail (which fetches
+winners via `getRaffleDrawRun`).
+
+## Action button decision matrix
+
+Per-draw CTA (evaluate in priority order):
+
+| Condition | CTA |
+|---|---|
+| `current_state === WinnerSelection` (2) | "Drawing now…" (informational) — show the Lottie drawing animation |
+| `current_state === Executed` (3) | "View winners" — opens detail via `getRaffleDrawRun` |
+| `requires_optin && user_opted_in && current_state !== Executed` | "Fully opted in" (informational pill, no click) |
+| `requires_optin && !user_opted_in && is_active && current_state !== Executed` | "Opt in" — invokes `requestRaffleOptin` |
+| `!requires_optin && is_active && current_state === Open` | "View prizes" (or no CTA — the user is automatically participating) |
+| `!is_active` and other terminal states | No CTA |
+
+Opt-in is per-run — when a recurring draw advances to a new run,
+`user_opted_in` resets to `false` on the new run. The Opt-in CTA
+returns even for users who opted in to the previous run.
+
+## Image / asset specs
+
+| Field | Documented source | Aspect | Used where |
+|---|---|---|---|
+| `TRaffle.image_url` | 890×193 px | ~4.6:1 | Raffle row header (desktop) |
+| `TRaffle.image_url_mobile` | 300×142 px | ~2.1:1 | Raffle row header (mobile) |
+| `TRaffleDraw.image_url` | 365×175 px | ~2:1 | Draw promo |
+| `TRaffleDraw.image_url_mobile` | 300×145 px | ~2:1 | Draw promo (mobile) |
+| `TRaffleDraw.icon_url` | 256×256 px | 1:1 | Draw icon (compact contexts) |
+| `TRaffleDraw.background_image_url` | 900×85 px | ~10.6:1 | Draw row background (desktop) |
+| `TRaffleDraw.background_image_url_mobile` | 1328×240 px | ~5.5:1 | Draw row background (mobile) |
+| `TRafflePrize.image_url` | 256×256 px | 1:1 | Prize card |
+
+Fallback chain (per element): brand-supplied placeholder if the
+field is empty. The SDK doesn't ship default images.
+
+## Status-specific visual treatments
+
+- **Open** (`current_state === 1`): full-color card with active
+  countdown. Show My-tickets / prizes prominently.
+- **WinnerSelection** (`current_state === 2`): show Lottie drawing
+  animation (full-screen overlay in the default Smartico UI). The
+  default UI polls every 3 s during this state.
+- **Executed** (`current_state === 3`): subtle desaturation; show
+  "View winners" CTA; surface "You won!" badge if any prize matches
+  the user.
+- **Grand** draws (`is_grand: true`): larger card, distinct accent
+  color, grand badge. Otherwise identical fields.
+- **Sold out** (ticket cap reached): banner + no opt-in CTA.
+
+## Countdown / timing format
+
+The default Smartico UI uses a hard-stamped `DD : HH : MM : SS`
+ticker counting down to `execution_ts`. CSS state classes:
+
+- Normal — default styling
+- `alert` — applied when < 5 minutes remain (yellow/amber accent)
+- `alarm` — applied when < 1 minute remains (red accent)
+
+**Polling escalation**: the widget polls
+[`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun)
+at a variable rate keyed to remaining time:
+
+- 30 s default
+- 10 s when < 5 minutes remain
+- 3 s when in `WinnerSelection` state
+
+For non-default UIs, mirror this pattern or use a constant 30 s
+poll — the cost is one network round-trip per poll tick.
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: render a skeleton grid sized to the
+  eventual layout.
+- **Loading (cache hit)**: do not render a loading state — the
+  promise resolves within a microtask.
+- **Empty result**: `[]` means no visible raffles. Render a neutral
+  empty-state illustration.
+- **Error**: keep the prior list if any; show a non-blocking error
+  banner; retry on next user-driven action.
+
+## Animations / transitions
+
+- **List entry**: cards fade-in on first render.
+- **WinnerSelection state**: full-screen Lottie animation while the
+  server selects winners.
+- **No celebration animation on claim** — the winner row updates
+  in-place. See `claimRafflePrize` UI guide.
+- **Opt-in success**: ~500 ms delay then UI state flip via
+  `onUpdate` refresh.
+
+## Mobile vs desktop
+
+- **Image source**: `*_url` for desktop, `*_url_mobile` for mobile.
+- **Draw row background**: desktop 900×85 px (wide strip); mobile
+  1328×240 px (taller hero treatment).
+- **Detail modal**: desktop centered modal with backdrop dim; mobile
+  full-screen slide-up sheet.
+
+## Performance
+
+- The 30 s cache deduplicates rapid refetches.
+- During an in-flight draw (WinnerSelection), polling
+  `getRaffleDrawRun` instead of `getRaffles` is cheaper — the latter
+  is a larger payload.
+- Image assets are CDN-served; lazy-load images below the fold.

package/docs/ui/raffles/UIGuide_requestRaffleOptin.md

@@ -0,0 +1,114 @@
+# UI Guide — `requestRaffleOptin`
+
+## Overview
+- Action-focused mutation. The user is on a draw card / detail
+  page for a draw with `requires_optin === true`, and they click
+  "Opt in".
+- Success (`err_code === 0`) means the user is registered for this
+  run. Tickets earned within the run's eligibility window will
+  participate in the draw.
+- Opt-in is **per-run** — recurring draws require a fresh opt-in
+  for each new run.
+
+## Argument mapping
+
+The three IDs come from different fields on the embedded draw:
+
+| Argument | Source |
+|---|---|
+| `raffle_id` | `TRaffle.id` (the parent raffle) |
+| `draw_id` | `TRaffleDraw.id` (schedule_id, **stable** across recurring runs) |
+| `raffle_run_id` | `TRaffleDraw.run_id` (per-execution instance ID) |
+
+Don't confuse `draw.id` with `draw.run_id` — both are needed.
+
+## Loading state
+
+- **Trigger**: set an in-flight flag (`optingIn = true`)
+  immediately on click.
+- **Visual**: replace the button label with animated dots; disable
+  the button.
+- **Reset**: clear the flag on response.
+
+## Idempotency UI guard
+
+The SDK does NOT prevent double-clicks. A second call on the same
+`raffle_run_id` returns `err_code === 1` with `err_message`
+indicating the user is already opted in. Guard the call site:
+
+```ts
+const [optingIn, setOptingIn] = useState(false);
+
+const onOptIn = async (draw: TRaffleDraw) => {
+  if (optingIn) return;                        // in-flight guard
+  if (draw.user_opted_in) return;              // already opted in
+  setOptingIn(true);
+  const r = await window._smartico.api.requestRaffleOptin({
+    raffle_id: raffleId,
+    draw_id: draw.id,        // schedule_id, NOT run_id
+    raffle_run_id: draw.run_id,
+  });
+  setOptingIn(false);
+  handleResponse(r);
+};
+```
+
+Treat `err_code === 1` with an "already opted in" message as
+**idempotent success** in the UI.
+
+## Action button decision matrix
+
+CTA label per state on the draw card (evaluate in priority order):
+
+| Condition | CTA |
+|---|---|
+| `current_state === Executed` (3) | No opt-in CTA (draw is finished) |
+| `current_state === WinnerSelection` (2) | No opt-in CTA (drawing in progress) |
+| `!requires_optin` | No opt-in CTA (tickets participate automatically) |
+| `requires_optin && user_opted_in` | Disabled "Fully opted in" pill (informational) |
+| `requires_optin && !user_opted_in && is_active && current_state !== Executed` | Enabled "Opt in" button |
+| `requires_optin && !is_active` | No opt-in CTA (draw is inactive) |
+
+After opt-in success, `user_opted_in` flips to `true` on the next
+`getRaffles` refresh (which fires automatically via `onUpdate`).
+
+## Per-error-code handling
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Show "Fully opted in" pill; success toast optional |
+| `1` + "already opted in" | Treat as success — same UI as above |
+| `1` + "no need to opt-in" | Hide the opt-in CTA — the draw doesn't actually require it |
+| `1` + "raffle id does not match" | Show a generic error toast; this is a programming bug — verify the IDs being passed |
+| `1` + control-group message | Show a gating message ("Not eligible") |
+| Other non-zero | Generic error toast with `err_message`. Allow retry. |
+
+## Refresh after response
+
+The SDK auto-refreshes the raffles cache on every opt-in response
+(success OR failure). The `onUpdate` callback registered via
+[`getRaffles`](../../api/classes/WSAPIRaffles.md#getraffles) fires
+with the refreshed list — `user_opted_in` reflects the new state.
+**Don't manually call `getRaffles()` after the opt-in response.**
+
+## Animations / transitions
+
+- **Loading dots**: 3-dot animation on the button while in flight.
+- **Success state flip**: button transitions from "Opt in" to
+  "Fully opted in" (~150 ms ease-out). The default Smartico UI
+  uses a 500 ms delay before re-fetching, then the state flip is
+  observed on the refreshed list.
+- **No celebration animation** — opt-in is a quiet success.
+
+## Mobile vs desktop
+
+- **Loading state**: identical (dots).
+- **CTA placement**: desktop usually inline on the draw row; mobile
+  may use a sticky CTA at the bottom of the draw detail.
+
+## Performance
+
+- Single round-trip per click.
+- The `getRaffles` auto-refresh after the response is a separate
+  network call (the cache is invalidated). For UIs that already
+  have fresh state, this is redundant but harmless.