@smartico/public-api 0.0.380 → 0.0.381

package/docs/ui/inbox/UIGuide_markInboxMessageAsRead.md

@@ -0,0 +1,122 @@
+# UI Guide — `markInboxMessageAsRead` (and `markAllInboxMessagesAsRead`)
+
+## Overview
+- Action-focused mutation. Two variants:
+  - **Single**: `markInboxMessageAsRead(messageGuid)` — flip one
+    message's read state.
+  - **Bulk**: `markAllInboxMessagesAsRead()` — flip every unread
+    message globally.
+- Both return `{ err_code, err_message }`. `err_code === 0` = success.
+- Both are idempotent — repeated calls on already-read targets
+  return `0`.
+- Auto-fires the unread-count update through the user-properties
+  channel; the inbox badge drops automatically.
+
+## When to call
+
+**Single (auto-mark)**: when the user opens a message detail view.
+The default Smartico UI fires this alongside
+{@link reportImpressionEvent} inside the message-open handler.
+
+```ts
+const onMessageOpen = async (msg: TInboxMessage) => {
+  if (!msg.read) {
+    await Promise.all([
+      window._smartico.api.markInboxMessageAsRead(msg.message_guid),
+      Promise.resolve(window._smartico.api.reportImpressionEvent({
+        engagement_uid: msg.message_guid,
+        activityType: 31,
+      })),
+    ]);
+    console.log('[smartico] message opened — marked read and impression reported in parallel');
+  }
+};
+```
+
+**Bulk (mark all)**: typically wired to a "Mark all as read"
+button in the inbox header. Reasonable to skip the in-flight
+loading state for this — the operation is fast and the UI updates
+are observable immediately.
+
+## Loading state
+
+- **Single**: optional. The mutation is fast enough (server
+  round-trip ~100–300 ms) that you can skip a visible loading state
+  and rely on optimistic UI.
+- **Bulk**: show a brief loading state on the "Mark all" button to
+  avoid double-clicks (the button should disable while pending).
+
+## Optimistic update
+
+Recommended for both variants — both are idempotent at the server,
+so revert risk is minimal:
+
+```ts
+// Single — flip local `read` flag immediately, then call.
+const target = { ...msg, read: true };
+updateLocalList(target);
+const r = await window._smartico.api.markInboxMessageAsRead(msg.message_guid);
+if (r.err_code !== 0) {
+  // Revert and show error.
+  updateLocalList(msg);
+  console.error('[smartico] mark-read failed, reverting:', r.err_message);
+}
+```
+
+```ts
+// Bulk — drop all unread dots immediately.
+const allRead = messages.map(m => ({ ...m, read: true }));
+setMessages(allRead);
+const r = await window._smartico.api.markAllInboxMessagesAsRead();
+if (r.err_code !== 0) {
+  // Revert.
+  setMessages(messages);
+}
+```
+
+## Refresh behavior
+
+- The inbox unread badge auto-updates via the user-properties
+  channel — subscribe to
+  [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)'s
+  `props_change` and watch `core_inbox_unread_count`, or use
+  [`getInboxUnreadCount`](../../api/classes/WSAPIInbox.md#getinboxunreadcount)'s
+  `onUpdate`. No need to refresh the count manually.
+- The message-list `onUpdate` does NOT fire — the SDK doesn't
+  auto-refresh `getInboxMessages` after these mutations. Either
+  update local state optimistically (recommended) or re-call
+  `getInboxMessages` if you need the server-canonical view.
+
+## Idempotency
+
+Both variants are idempotent at the server:
+
+- `markInboxMessageAsRead(sameGuid)` twice → both calls return
+  `err_code === 0`. Already-read state is preserved.
+- `markAllInboxMessagesAsRead()` on an empty / all-read inbox →
+  returns `err_code === 0`. No-op.
+
+Consumer-side, the bulk operation may race with a new message
+arriving server-side between the call and processing. The new
+message remains unread. Subsequent `getInboxMessages` calls show
+it as unread.
+
+## Error handling
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Hide unread dot(s); update badge automatically via push. |
+| Other non-zero | Revert local state if optimistic; show a non-blocking error toast with `err_message`. Allow retry. |
+
+## Animations / transitions
+
+- **Unread dot fade**: 200 ms opacity transition from 1 → 0 on
+  mark-read.
+- **Bulk mark-all**: stagger the dot fade across rows (~30 ms per
+  row) for a sweep effect.
+
+## Mobile vs desktop
+
+- **Auto-mark trigger**: identical (on detail open).
+- **Mark-all button**: typically in a header overflow menu on
+  mobile; inline in the desktop header.

package/docs/ui/inbox/UIGuide_markUnmarkInboxMessageAsFavorite.md

@@ -0,0 +1,84 @@
+# UI Guide — `markUnmarkInboxMessageAsFavorite`
+
+## Overview
+- Toggles a message's `favorite` (starred) flag. Pass `mark: true`
+  to favorite, `mark: false` to unfavorite.
+- Returns `{ err_code, err_message }`. `err_code === 0` = success.
+- Idempotent — repeat calls with the same `mark` value return
+  `err_code === 0` with no-op effect.
+
+## When to call
+
+Inline star-icon click handler on each list row + (optionally) in
+the detail view header.
+
+```ts
+const onToggleFavorite = async (msg: TInboxMessage) => {
+  const target = !msg.favorite;
+  console.log('[smartico] optimistically flip star to', target);
+  // Update local state first.
+  updateLocalList({ ...msg, favorite: target });
+
+  const r = await window._smartico.api.markUnmarkInboxMessageAsFavorite(
+    msg.message_guid,
+    target,
+  );
+
+  if (r.err_code !== 0) {
+    // Revert.
+    updateLocalList(msg);
+    console.error('[smartico] favorite failed, reverting:', r.err_message);
+  } else {
+    console.log('[smartico] favorite toggle succeeded — show a brief "Added to favorites" / "Removed from favorites" toast');
+  }
+};
+```
+
+## Loading state
+
+Optional. The operation is fast and the icon state itself provides
+visible feedback. Many UIs skip a loading state and rely on
+optimistic updates.
+
+If you do show a loading state, dim the star icon briefly
+(~150 ms) during the in-flight call.
+
+## Optimistic update
+
+Recommended. The server is idempotent and accepts the requested
+target value regardless of prior state, so optimistic UI almost
+never produces a revert.
+
+## Refresh behavior
+
+- No subscription / push refresh fires for favorite changes.
+- The favorite/starred filter (`onlyFavorite: true` on
+  [`getInboxMessages`](../../api/classes/WSAPIInbox.md#getinboxmessages))
+  reflects the new state on the next call — important for the
+  "Favorite" tab.
+- After toggling on the All tab, the row's star icon updates
+  optimistically. If the user is on the Favorite tab, an
+  unfavorited row should be removed from the list (since the
+  filter excludes it).
+
+## Error handling
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Keep optimistic star state; show "Added to favorites" / "Removed from favorites" toast. |
+| Other non-zero | Revert local star state; show non-blocking error toast with `err_message`. Allow retry. |
+
+## Animations / transitions
+
+- **Star toggle**: scale-pulse (~100 ms) on tap.
+- **Color fade**: 150 ms fill color transition (outline → filled
+  or vice versa).
+- **Tab transition**: when an unfavorited row should disappear
+  from the Favorite tab, slide it out (~200 ms) before removing.
+
+## Mobile vs desktop
+
+- **Star visibility**: always visible on mobile; hover-visible on
+  desktop (to reduce visual noise on the list).
+- **Tap target**: 44×44 px minimum on mobile.
+- **Toast position**: mobile bottom; desktop top-right.

package/docs/ui/jackpots/UIGuide_getJackpotEligibleGames.md

@@ -0,0 +1,73 @@
+# UI Guide — `getJackpotEligibleGames`
+
+## Overview
+- Returns the casino games that contribute to a specific jackpot.
+- Powers the "Eligible Games" tab inside the jackpot detail modal.
+- 30 s cache; no push subscription.
+- **Skip this call entirely** when
+  [`JackpotDetails`](../../api/interfaces/JackpotDetails.md)`.ach_related_game_allow_all === true`
+  — every game contributes, no list needed.
+
+## Pre-flight check
+
+```ts
+const [jp] = await window._smartico.api.jackpotGet({ jp_template_id });
+
+if (jp?.ach_related_game_allow_all) {
+  console.log('[smartico] every game contributes — hide the eligible games tab entirely');
+  return;
+}
+
+const r = await window._smartico.api.getJackpotEligibleGames({ jp_template_id });
+```
+
+## List view organization
+
+The response shape is `{ eligible_games: JackpotEligibleGame[] }`. The
+default Smartico UI renders games as a grid of tiles, sorted by their
+server-provided `priority` (ascending).
+
+## Item tile
+
+| Field | Source | Notes |
+|---|---|---|
+| Thumbnail | `image` | Square aspect ratio; ~120×120 px tile |
+| Name | `name` | Below the thumbnail |
+| Provider | `game_provider` | Small chip / secondary text |
+| Status | `enabled` | Dim / hide tiles with `enabled === false` |
+
+**Click target**: tap → open the game (operator-defined launch via
+`link` / `mobile_spec_link`).
+
+## `onUpdate` caveat
+
+The method accepts an `onUpdate` callback to match the SDK's
+subscription contract — but no server push is currently wired to fire
+it automatically. Treat the callback as a no-op for now and refresh
+manually if needed.
+
+## Empty / loading / error states
+
+- **Empty**: "No eligible games" — uncommon; usually means operator
+  misconfiguration.
+- **Loading (cold fetch)**: skeleton tile grid.
+- **Error**: keep prior list if any; non-blocking banner.
+
+## Refresh
+
+- 30 s SDK cache per `jp_template_id`.
+- Cache does NOT clear on opt-in / opt-out / win events — eligible-game
+  lists rarely change during a session.
+- For long sessions, re-call when reopening the tab past the 30 s
+  window.
+
+## Mobile vs desktop
+
+- **Mobile**: 2- or 3-column tile grid.
+- **Desktop**: 4- or 5-column tile grid.
+
+## Performance
+
+- Lazy-load — call only when the user opens the Eligible Games tab.
+- 30 s cache absorbs rapid tab switches.
+- Skip entirely on `ach_related_game_allow_all === true` jackpots.

package/docs/ui/jackpots/UIGuide_getJackpotWinners.md

@@ -0,0 +1,83 @@
+# UI Guide — `getJackpotWinners`
+
+## Overview
+- Paginated list of past winners of a specific jackpot template.
+- Powers the "Recent Winners" / "Win History" tab inside the jackpot
+  detail modal.
+- 30 s cache per template.
+- Gated by the operator's `expose_winners_over_api` flag — but only on
+  the client side. Custom UIs must check this flag before calling.
+
+## Gating — respect `expose_winners_over_api`
+
+The server does NOT enforce this flag. The consumer is responsible for
+honoring the operator's choice:
+
+```ts
+const [jp] = await window._smartico.api.jackpotGet({ jp_template_id });
+
+if (!jp || !jp.expose_winners_over_api) {
+  console.log('[smartico] winners hidden by operator — hide the winners tab');
+  return;
+}
+
+const winners = await window._smartico.api.getJackpotWinners({ jp_template_id });
+```
+
+Failing to check the flag will display winners on widgets where the
+operator intended to keep them private.
+
+## List view organization
+
+Server-sorted newest-first. No client-side sort needed. Pagination via
+`limit` (default 20) and `offset`. For infinite scroll, advance `offset`
+by `limit` per page.
+
+## Item row
+
+| Field | Source | Notes |
+|---|---|---|
+| Win date | `win_date_ts` | Unix ms; format as `DD/MM/YYYY · HH:mm` or relative |
+| Username | `winner.public_username` | May be partially masked by operator settings |
+| Avatar | `winner.avatar_url` | 32–40 px square |
+| Amount | `winner.winning_amount_jp_currency` | **In jackpot's native currency, NOT user currency** |
+| Currency | `jp_currency` from the parent `JackpotDetails` | Pair with the amount field |
+
+## Currency caveat
+
+Amounts here are in the jackpot's native currency (`jp_currency` on the
+parent `JackpotDetails`), NOT in the user's wallet currency. If the
+display needs the user-currency equivalent, the consumer must convert
+client-side using the exchange rate available on the platform.
+
+## Empty / loading / error states
+
+- **Empty (page 0)**: "No winners yet — be the first!"
+- **Empty (subsequent pages)**: end-of-list — stop pagination.
+- **Loading (cold fetch)**: skeleton row list (3–5 placeholders).
+- **Error**: keep prior list if any; non-blocking banner.
+
+## Refresh
+
+- 30 s SDK cache per `jp_template_id`.
+- Cache clears on jackpot-win push events — when the pot explodes, the
+  new winner row appears on the next call.
+- Cache also clears on opt-in / opt-out.
+
+## Animations / transitions
+
+- New winner row (after a jackpot-win push) — fade-in or pulse at the
+  top of the list.
+- Skeleton rows during initial load.
+
+## Mobile vs desktop
+
+- **Mobile**: full-width rows with avatar left, amount right.
+- **Desktop**: same layout, max-width centered modal.
+
+## Performance
+
+- 30 s cache absorbs rapid tab switches.
+- Paginate via `limit`/`offset` — default `limit: 20` is typically
+  sufficient.
+- Don't pre-fetch — the winners tab is opened on demand.

package/docs/ui/jackpots/UIGuide_jackpotGet.md

@@ -0,0 +1,138 @@
+# UI Guide — `jackpotGet`
+
+## Overview
+- Returns the user-eligible jackpots with their live pot snapshots.
+- Designed for 1-Hz polling — the SDK uses a 30 s cache for templates and
+  a 1 s cache for pot values so a fast poll produces a smooth counting-up
+  pot effect.
+- No push subscription. Win events clear the caches; subsequent polls
+  pick up the new state.
+
+## List view organization
+
+The default Smartico UI renders jackpots in a 2-column grid sorted by
+`is_opted_in` ascending — not-opted-in jackpots come FIRST so the user
+sees joinable opportunities before their existing memberships. Cards
+stagger-fade in at 100 ms per index.
+
+| Property | Value |
+|---|---|
+| Grid layout | 2 columns (mobile and desktop) |
+| Sort | `is_opted_in` ascending (not-opted-in first) |
+| Tabs / filters | None — single flat grid |
+
+## Item card / tile
+
+| Field | Source | Notes |
+|---|---|---|
+| Background image | `jp_public_meta.image_url` | Gradient overlay; CSS background |
+| Name | `jp_public_meta.name` | HTML supported |
+| Pot amount | `pot.current_pot_amount_user_currency` | User wallet currency |
+| Currency symbol | `user_currency` | Looked up by translation key |
+| Status pill | derived | "Opted in" if `is_opted_in`, otherwise nothing |
+| Registration count | `registration_count` | Shown on the home-card variant only |
+| CTA button | derived | "Join Jackpot" if `!is_opted_in`, otherwise "Details" |
+
+**Click target**: whole-card tap → open detail modal.
+
+## Detail view / popup
+
+The detail modal has three potential tabs:
+
+| Tab | Condition shown | Content |
+|---|---|---|
+| **Rules** | Always | `jp_public_meta.description` as HTML |
+| **Eligible Games** | `ach_related_game_allow_all === false` | Async fetch via [`getJackpotEligibleGames`](../../api/classes/WSAPIJackpots.md#getjackpoteligiblegames); tile grid |
+| **Win History** | `expose_winners_over_api === true` | Async fetch via [`getJackpotWinners`](../../api/classes/WSAPIJackpots.md#getjackpotwinners); infinite scroll |
+
+Header shows the live pot amount with `current_pot_amount_user_currency`
+and a bouncy animation on modal open.
+
+## Polling for a live counter
+
+The default Smartico UI calls `jackpotGet()` every 1 second while the
+jackpots page is mounted. The SDK's split cache (30 s template / 1 s pot)
+makes this efficient — only the pot values are re-fetched per second,
+not the static template data.
+
+```ts
+useEffect(() => {
+  const i = setInterval(async () => {
+    const jackpots = await window._smartico.api.jackpotGet();
+    console.log('[smartico] update each pot card with the new amount and temperature');
+  }, 1000);
+  return () => clearInterval(i);
+}, []);
+```
+
+For a single-jackpot widget (e.g. on a casino game page), pass a filter:
+
+```ts
+const r = await window._smartico.api.jackpotGet({ related_game_id: 'gold-slot2' });
+```
+
+## Currency display rules
+
+Two currency fields on `pot`:
+
+| Use case | Field | Currency |
+|---|---|---|
+| Card / modal pot amount | `current_pot_amount_user_currency` | `user_currency` |
+| Wire amount in jackpot's native currency | `current_pot_amount` | `jp_currency` |
+
+The default Smartico UI always renders user-currency on cards. Use the
+native-currency value only when correlating with `getJackpotWinners`
+results (which return amounts in `jp_currency`).
+
+## Temperature visual treatment
+
+`pot.current_pot_temperature` is one of `JackPotTemparature` (0 = COLD,
+1 = WARM, 2 = HOT, 3 = BURNING). The default Smartico UI does NOT
+currently render distinct treatments per temperature — the field is
+available for custom UIs to apply color, glow, or animation:
+
+| Temperature | Suggested visual |
+|---|---|
+| `COLD` (0) | Neutral / blue accent |
+| `WARM` (1) | Amber accent |
+| `HOT` (2) | Red accent + pulse animation |
+| `BURNING` (3) | Red + glow + faster pulse |
+
+For `JackpotType.Personal` jackpots, temperature push events are
+suppressed server-side; the value still updates but transitions are not
+broadcast.
+
+## Image / asset specs
+
+| Field | Use | Notes |
+|---|---|---|
+| `jp_public_meta.image_url` | Card background + modal header | Operator-defined; no fixed aspect ratio |
+| `jp_public_meta.winner_template` | HTML rendered to the winner after a hit | Operator-authored |
+| `jp_public_meta.not_winner_template` | HTML rendered to losers | Operator-authored |
+
+## Refresh
+
+- 30 s template cache + 1 s pot cache.
+- Caches clear on opt-in / opt-out / jackpot-win push.
+- Filter changes flush both caches.
+- No `onUpdate` subscription on this method.
+
+## Empty / loading / error states
+
+- **Empty**: no jackpot eligible for the user — typically render a
+  "No jackpots available right now" placeholder, or omit the section.
+- **Loading (cold fetch)**: skeleton card placeholders.
+- **Error**: keep the prior grid if any; non-blocking banner.
+
+## Mobile vs desktop
+
+- **Grid**: 2-column on both.
+- **Card components**: mobile uses `JackpotMobileItem`, desktop uses
+  `JackpotItemUI`; visual treatment is otherwise identical.
+
+## Performance
+
+- 1 Hz polling is the intended cadence — fast enough for a smooth pot
+  counter, slow enough to be cheap.
+- Don't add a client-side cache on top — the SDK's split cache already
+  optimizes the common case.

package/docs/ui/jackpots/UIGuide_jackpotOptIn.md

@@ -0,0 +1,85 @@
+# UI Guide — `jackpotOptIn`
+
+## Overview
+- Opts the user into a jackpot. After this, the user contributes to the
+  pot per their bets and is eligible to win.
+- SDK clears the jackpot caches on success — the next
+  [`jackpotGet`](../../api/classes/WSAPIJackpots.md#jackpotget) call returns
+  `is_opted_in: true`.
+- Mutation only; no follow-up data; result is just `{errCode, errMsg}`.
+
+## Loading state
+
+User taps "Join Jackpot" → button enters spinner state.
+
+```ts
+const [joining, setJoining] = useState(false);
+
+const onJoin = async () => {
+  if (joining) return;
+  setJoining(true);
+  const r = await window._smartico.api.jackpotOptIn({ jp_template_id });
+  setJoining(false);
+  handleResult(r);
+};
+```
+
+## Idempotency guard
+
+The SDK does not prevent double-tap. Guard at the call site as above.
+Re-tap behavior:
+
+| State | Server response |
+|---|---|
+| Already opted in (active registration) | Non-zero `errCode` ("Already opted in") |
+| Previously opted in then opted out | Succeeds — re-activates registration |
+
+## Action button decision matrix
+
+| Result | UI action |
+|---|---|
+| `errCode === 0` | Close modal or update card; show "You're in!" confirmation; refresh the jackpot card to display the opt-out CTA |
+| `errCode !== 0` | Show error toast with `errMsg`; keep modal open for retry |
+
+The default Smartico UI shows a generic error modal on any non-zero
+`errCode`, without parsing `errMsg`. Custom UIs should surface the
+server-provided message for clearer user feedback.
+
+## Refresh after success
+
+- SDK clears the template, pot, and winners caches automatically.
+- The next [`jackpotGet`](../../api/classes/WSAPIJackpots.md#jackpotget)
+  returns `is_opted_in: true` and an incremented `registration_count`.
+- No optimistic update — wait for the result before flipping the card's
+  CTA label. Locked-segment / inactive-template rejections are real and
+  would produce a flicker if you optimistically toggled.
+
+## Side effects
+
+- Fires a `JACKPOT_OPT_IN` operator-side engagement event (visible to
+  automation rules / campaigns).
+- Does NOT immediately deduct points / gems — contributions happen
+  per-bet during gameplay.
+- `registration_count` increments on the next `jackpotGet()`.
+
+## Visitor mode
+
+Not supported. The SDK throws synchronously when called via `_smartico.vapi()`.
+
+## Animations / transitions
+
+- Tap → button morphs to spinner.
+- On `errCode === 0` → "Joined!" confirmation pulse, card CTA swaps to
+  "Opt Out".
+- On error → spinner clears; error toast slides in.
+
+## Mobile vs desktop
+
+- **Mobile**: full-width "Join Jackpot" button anchored at the bottom of
+  the modal.
+- **Desktop**: button bottom-right of the centered modal.
+
+## Performance
+
+- Single round-trip. Cache invalidation is automatic — don't manually
+  refetch unless polling.

package/docs/ui/jackpots/UIGuide_jackpotOptOut.md

@@ -0,0 +1,65 @@
+# UI Guide — `jackpotOptOut`
+
+## Overview
+- Opts the user out of a jackpot. Stops future contributions and removes
+  win eligibility.
+- Reversible — the user can re-join via
+  [`jackpotOptIn`](../../api/classes/WSAPIJackpots.md#jackpotoptin).
+- Past contributions to the current pot remain — opt-out does not refund.
+
+## Loading state
+
+Same pattern as
+[`jackpotOptIn`](../../api/classes/WSAPIJackpots.md#jackpotoptin):
+spinner + guard against double-tap.
+
+## Action button decision matrix
+
+| Result | UI action |
+|---|---|
+| `errCode === 0` | Confirmation message; refresh card to show join CTA |
+| `errCode !== 0` (`errMsg` like "Already opted out") | Show error toast with `errMsg` |
+
+## Idempotency
+
+| Prior state | Server response |
+|---|---|
+| Currently opted in | Success |
+| Already opted out (registration exists with optout_date set) | Non-zero `errCode` |
+| Never opted in (no registration row) | Typically succeeds silently |
+
+## Confirmation prompt
+
+Because opt-out is a destructive action (stops future contributions), the
+default Smartico UI shows a confirmation prompt before sending the
+request:
+
+> "Stop contributing to this jackpot? You can rejoin anytime."
+
+Custom UIs may skip the confirmation for power users but the prompt
+prevents accidental opt-outs.
+
+## Refresh after success
+
+- SDK clears the template, pot, and winners caches.
+- Next [`jackpotGet`](../../api/classes/WSAPIJackpots.md#jackpotget)
+  returns `is_opted_in: false` and a decremented `registration_count`.
+
+## Side effects
+
+- Fires `JACKPOT_OPT_OUT` operator-side event.
+- Past contributions remain on the pot — opt-out only stops FUTURE
+  contributions.
+
+## Visitor mode
+
+Not supported.
+
+## Mobile vs desktop
+
+- **Mobile**: opt-out button at the bottom of the detail modal.
+- **Desktop**: opt-out button bottom-right of the centered modal.
+
+## Performance
+
+Single round-trip.