@smartico/public-api 0.0.380 → 0.0.381

package/docs/ui/general/UIGuide_getRelatedItemsForGame.md

@@ -0,0 +1,140 @@
+# UI Guide — `getRelatedItemsForGame`
+
+## Overview
+- Returns the missions and tournaments that reference a casino / sportsbook
+  game in the operator's catalog.
+- Use to surface "X missions / Y tournaments feature this game" badges on
+  game tiles, lobby cards, or dedicated game detail screens.
+- Server applies user-eligibility filtering — results are already scoped to
+  what this user should see.
+- No cache; every call is a live round-trip.
+
+## Trigger points
+
+When to call:
+
+| Surface | Trigger |
+|---|---|
+| Game tile in lobby | Hover (desktop) / focus (mobile) — debounce 300 ms |
+| Game detail page | Mount |
+| Tournament detail "Related Games" panel | Mount (the reverse direction — `tournament.related_games[]` lists games, this method goes game → tournament) |
+| Mission detail panel | Mount alongside the mission's own data |
+
+Do NOT call on every game tile render — the response is not cached and
+network roundtrips per tile will overwhelm the connection. Use lazy / hover-
+triggered loading.
+
+## Result rendering
+
+The response has two arrays:
+
+```ts
+{
+  achievements: UserAchievement[];  // missions (same shape as getMissions)
+  tournaments?: Tournament[];        // tournaments (same shape as getTournamentsList)
+}
+```
+
+Both may be empty / undefined. The shape mirrors `getMissions` and
+`getTournamentsList` — no reduced subset, no different field semantics.
+
+### Quick badge (game tile overlay)
+
+For a small overlay on a game tile:
+
+```ts
+const r = await window._smartico.api.getRelatedItemsForGame(gameId);
+const total = (r.achievements?.length ?? 0) + (r.tournaments?.length ?? 0);
+
+if (total > 0) {
+  console.log('[smartico] show a "+' + total + '" badge on the game tile');
+}
+```
+
+The default Smartico UI uses a small accent badge with the total count and an
+icon hinting at gamification (typically a star or trophy).
+
+### Full panel (game detail / mission / tournament context)
+
+For a detail panel:
+
+| Section | Source | Layout |
+|---|---|---|
+| "Missions featuring this game" | `r.achievements` | Vertical list, mission card per item |
+| "Tournaments featuring this game" | `r.tournaments` | Horizontal scroll or vertical list, tournament card per item |
+
+Use the same card layouts as `getMissions` (see
+[`getMissions`](../../api/classes/WSAPIMissions.md#getmissions) UI guide) and
+`getTournamentsList` (see
+[`getTournamentsList`](../../api/classes/WSAPITournaments.md#gettournamentslist)
+UI guide). Field semantics are identical.
+
+## Empty results
+
+Empty results are the default for most games — operators typically link
+missions / tournaments to specific featured games, not the entire catalog.
+
+UI options:
+
+- **Game tile overlay**: hide the badge entirely (don't render an empty
+  "0 missions" placeholder).
+- **Detail panel**: omit the panel when both arrays are empty. The default
+  Smartico UI shows a small "No related missions or tournaments" message
+  only when the user explicitly opens a dedicated "Related" tab and it's
+  empty.
+
+## Refresh
+
+- **No cache** — every call hits the server.
+- Re-call after:
+  - The user opts into or completes a related mission (to refresh the
+    progress/status displayed on the badge).
+  - The user navigates between games.
+- Do NOT build a consumer-side cache for UI-critical paths — missions and
+  tournaments are live-operated state and stale data would mis-render
+  eligibility.
+
+## Loading state
+
+The call typically returns in 100–300 ms. UI patterns:
+
+- **Game tile overlay**: render the tile immediately; show the badge once
+  the call resolves. No spinner.
+- **Detail panel**: show a skeleton row layout (1–3 placeholder rows) while
+  loading.
+
+## Error handling
+
+The method returns the raw protocol response. Inspect transport-level
+exceptions via try/catch:
+
+```ts
+try {
+  const r = await window._smartico.api.getRelatedItemsForGame('gold-slot2');
+  // ...
+} catch (e) {
+  console.error('[smartico] related items fetch failed — hide the related badge:', e);
+}
+```
+
+## Visitor mode
+
+Documented as supported via `_smartico.vapi(lang).getRelatedItemsForGame(...)`,
+but in practice the server may require an authenticated user for the
+eligibility filtering to work. Visitor calls have been seen to fail in some
+deployments — test the specific deployment before relying on it.
+
+## Mobile vs desktop
+
+- **Mobile**: overlay badges on tiles; tap-through to a sheet with the
+  related items.
+- **Desktop**: hover-overlay or always-visible badges; click to open the
+  related panel in a sidebar or modal.
+
+## Performance
+
+- One round-trip per game ID. No cache.
+- Debounce hover-triggered calls (300 ms) to avoid spurious requests when
+  the user moves the cursor across tiles.
+- Pre-fetch on game tile mount only if the lobby is small (< 20 tiles);
+  otherwise lazy-load on user interest.

package/docs/ui/inbox/UIGuide_deleteInboxMessage.md

@@ -0,0 +1,135 @@
+# UI Guide — `deleteInboxMessage` (and `deleteAllInboxMessages`)
+
+## Overview
+- Soft-deletes inbox messages. Two variants:
+  - **Single**: `deleteInboxMessage(messageGuid)` — drop one message.
+  - **Bulk**: `deleteAllInboxMessages()` — drop every message
+    globally.
+- Both return `{ err_code, err_message }`. `err_code === 0` =
+  success.
+- **No undelete via the SDK** — deletion is server-recorded but
+  the user cannot recover the message. Recovery requires operator
+  intervention.
+- Both are idempotent at the server.
+
+## When to call
+
+**Single**: from a delete affordance per row:
+
+| Trigger | Platform | Notes |
+|---|---|---|
+| Trash icon click (hover-visible) | Desktop | |
+| Swipe past threshold (~75 px) | Mobile | Left or right swipe, with CSS `translateX(±100%)` |
+| Delete button in detail panel | Desktop full-page | When the message is open in the right-side panel |
+
+**No confirm dialog** for the single-message delete — the action
+is fast and the user's intent is explicit (they clicked / swiped).
+
+**Bulk**: typically in a header overflow menu under "Delete all
+messages". **Surface a confirm dialog** for the bulk variant —
+this is destructive at scale and there is no undo.
+
+```ts
+// Single — swipe handler
+const onDelete = async (msg: TInboxMessage) => {
+  // Optimistic: drop from local list immediately.
+  removeFromLocalList(msg.message_guid);
+
+  const r = await window._smartico.api.deleteInboxMessage(msg.message_guid);
+  if (r.err_code !== 0) {
+    // Revert.
+    restoreToLocalList(msg);
+    console.error('[smartico] delete failed, restored:', r.err_message);
+  } else {
+    console.log('[smartico] message deleted — show "Message deleted" toast (no undo affordance)');
+  }
+};
+
+// Bulk — after confirm dialog
+const onDeleteAll = async () => {
+  const previousMessages = messages;
+  setMessages([]);
+
+  const r = await window._smartico.api.deleteAllInboxMessages();
+  if (r.err_code !== 0) {
+    setMessages(previousMessages);
+    console.error('[smartico] delete-all failed, restored:', r.err_message);
+  } else {
+    console.log('[smartico] all messages deleted — inbox cleared, badge auto-drops to 0');
+  }
+};
+```
+
+## Loading state
+
+- **Single**: skip the explicit loading state — the row animates
+  out (slide ~300 ms) and the perceived feedback is the row
+  disappearing.
+- **Bulk**: show loading dots on the "Delete all" button while
+  pending; disable the button to prevent double-clicks.
+
+## Optimistic update
+
+Recommended for both variants:
+
+- **Single**: drop the row from local state before the call.
+  Revert by re-adding it at the same index if the call fails.
+- **Bulk**: replace `messages` with `[]` immediately. Revert by
+  restoring the snapshot if the call fails.
+
+The risk of a revert is low — the server is idempotent and the
+soft-delete operation rarely fails outside of transport issues.
+
+## Refresh behavior
+
+- `getInboxMessages` `onUpdate` does NOT fire on delete — the SDK
+  doesn't auto-refresh the list.
+- The unread badge auto-updates via the user-properties channel
+  (any deleted unread messages drop from the count).
+- For bulk delete, the badge drops to 0 (or near 0 if a new
+  message arrived mid-operation).
+
+## Idempotency
+
+Both variants are idempotent at the server:
+
+- `deleteInboxMessage(alreadyDeletedGuid)` → returns
+  `err_code === 0`. Already-deleted messages are filtered out
+  server-side, so the server sees no work to do.
+- `deleteAllInboxMessages()` on an empty inbox → returns
+  `err_code === 0`. No-op.
+
+## No undo
+
+There is **no undelete path via the SDK**. The default Smartico
+UI does NOT offer an undo affordance after delete. If your
+product surface needs an undo pattern, implement it
+client-side using an optimistic deferred call: stash the row in
+local state, show a "Message deleted [Undo]" toast for ~5 s,
+and only fire `deleteInboxMessage` when the toast dismisses.
+
+## Error handling
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Drop locally; show "Message deleted" toast (single) or "All messages deleted" toast (bulk). |
+| Other non-zero | Revert local state (restore row(s)); show non-blocking error toast with `err_message`. Allow retry. |
+
+## Animations / transitions
+
+- **Single delete (swipe)**: row slides off-screen
+  (`translateX: ±100%`, 300 ms ease-out), then collapses height
+  (200 ms).
+- **Single delete (click)**: row collapses height + fades opacity
+  (200 ms each).
+- **Bulk delete**: list fades to empty state animation.
+
+## Mobile vs desktop
+
+- **Trigger**: mobile = swipe (left or right past threshold);
+  desktop = hover-visible trash icon.
+- **RTL**: swipe direction flips with `direction: rtl` —
+  `translateX(+100%)` becomes the swipe-left animation.
+- **Bulk delete UI**: mobile = in the overflow menu;
+  desktop = inline in the inbox header (still behind a confirm
+  dialog).

package/docs/ui/inbox/UIGuide_getInboxMessageBody.md

@@ -0,0 +1,133 @@
+# UI Guide — `getInboxMessageBody`
+
+## Overview
+- Returns the rich body (title, preview, icon, action, html_body,
+  buttons, custom_data) for one message identified by its
+  `message_guid`.
+- Fetched from a CDN, NOT over the WebSocket — latency depends on
+  CDN proximity. No SDK-level cache (browser HTTP cache may apply
+  via CDN Cache-Control headers).
+- Use in two contexts: (a) co-fetched with the envelope list for
+  rendering list-row titles + previews, (b) on-demand for a detail
+  view.
+
+## Detail view layout
+
+Top-to-bottom layout for a full message detail:
+
+  1. **Icon** — `body.icon` at a larger render size (typically
+     128×128 px to match the source). Center-aligned at top.
+  2. **Title** — `body.title`, primary heading.
+  3. **Body content** — branches on `body.action`:
+     - `'dp:inbox'` → render `body.html_body` in a sandboxed
+       iframe (see "Rich vs simple" below).
+     - any other value → render `body.preview_body` as a formatted
+       text block.
+  4. **Buttons** — `body.buttons[]` (max 2) — only when
+     `action === 'dp:inbox'`. Render side-by-side or stacked
+     depending on width.
+  5. **CTA** — single primary CTA driving `body.action` when the
+     message has no `html_body` (i.e. `action !== 'dp:inbox'`).
+
+## Rich vs simple messages
+
+| `action` value | Shape | Render |
+|---|---|---|
+| `'dp:inbox'` | Rich: has `html_body`, optional `buttons[]` (max 2) | Sandboxed iframe + button row |
+| Anything else (`'dp:gf_missions'`, `'https://...'`, etc.) | Simple: title + preview only | Title + `preview_body` + single CTA wired to `action` |
+
+The transform inside the SDK enforces this — if the underlying CDN
+payload has `html_body` or `buttons` but the action isn't
+`'dp:inbox'`, those fields are stripped before reaching the SDK
+consumer. Don't try to render `html_body` for non-`'dp:inbox'`
+messages — it will be `undefined`.
+
+## Sandboxed iframe (for `html_body`)
+
+`html_body` is operator-supplied HTML. **Render in a sandboxed
+iframe** to prevent script execution in your host page:
+
+```ts
+// Recommended pattern (data: URL, no script execution).
+const html = sanitize(body.html_body);
+const iframe = document.createElement('iframe');
+iframe.sandbox = '';  // no extra permissions
+iframe.srcdoc = html;
+container.appendChild(iframe);
+```
+
+The default Smartico UI uses an injected ResizeObserver script to
+auto-size the iframe height to its content. If you replicate this,
+include the script inside `srcdoc` (not as a sandbox permission) so
+the host page stays isolated.
+
+Wrap any deep-links found inside the HTML body with a click handler
+that calls `_smartico.dp(href)` rather than letting the native
+navigation execute — this keeps deep-link routing consistent.
+
+## Action button decision matrix
+
+| Condition | Button label | Click behavior |
+|---|---|---|
+| `body.action === 'dp:inbox'` AND no `buttons` | (no top-level CTA) | Action buttons (if any) are the primary affordances. The "open this message" deep-link is satisfied by being in the detail view already. |
+| `body.action === 'dp:inbox'` AND `buttons` non-empty | Render each `button.text` | Click handler executes `_smartico.dp(button.action)` AND fires {@link reportClickEvent} with `action: button.action`. |
+| `body.action !== 'dp:inbox'` (simple message) | Single CTA (operator usually puts text in `preview_body`; consumer may default to "Open") | Click handler executes `_smartico.dp(body.action)` AND fires {@link reportClickEvent} with `action: body.action`. |
+
+The default Smartico UI does NOT render an explicit "Close" or
+"Back" button inside the detail body — modal/sheet chrome handles
+that.
+
+## Telemetry pairing
+
+- Fire {@link reportImpressionEvent} when the detail view opens (or
+  the message first becomes visible).
+- Fire {@link reportClickEvent} when any action button or CTA is
+  tapped. Pass the deep-link / URL as the `action` argument so
+  operator analytics can attribute the click to the specific link.
+
+## `custom_data`
+
+Operator-defined per-message data. The SDK auto-parses
+JSON-looking strings, so at runtime `custom_data` is `any` despite
+the `string` type. Guard with `typeof custom_data === 'object'`
+before property access; treat non-object values as raw strings.
+
+Common consumer patterns:
+- A custom badge / category-color derived from a `custom_data.tag`
+  field.
+- A deep-link override for specific message types.
+- Operator-defined A/B variant identifier.
+
+## Empty / loading / error states
+
+- **Loading**: render a skeleton block in the detail panel — icon
+  placeholder, title placeholder, 3–4 lines of preview placeholder.
+- **Error**: CDN fetch failures should fall back to displaying the
+  envelope's `sent_date` and a "Message body unavailable, please
+  try again" placeholder. Allow retry.
+
+## Animations / transitions
+
+- **Detail open (mobile inline)**: 0.5 s height transition.
+- **Detail open (desktop panel)**: 150 ms fade.
+- **Iframe height adjust** (rich body): smooth height transition
+  via ResizeObserver — avoid jitter on small content changes.
+
+## Mobile vs desktop
+
+- **Modal style**: mobile inline expand or full-screen sheet;
+  desktop right-panel.
+- **Icon size**: desktop ~128 px; mobile may scale down to 64 px
+  to save vertical space.
+- **Button layout**: side-by-side on desktop; stacked on mobile
+  for thumb reach.
+
+## Performance
+
+- Each call is a CDN HTTP GET. For a list of 20 messages, parallel
+  body fetches via `Promise.all()` complete in roughly one CDN
+  round-trip time.
+- Cache bodies in your application state — the SDK does not cache
+  them, and re-opening a message would otherwise refetch.
+- Browser HTTP cache (Cache-Control from the CDN) provides some
+  free caching on repeat fetches within a session.

package/docs/ui/inbox/UIGuide_getInboxMessages.md

@@ -0,0 +1,186 @@
+# UI Guide — `getInboxMessages`
+
+## Overview
+- Returns the lightweight `TInboxMessage[]` envelopes — newest first.
+- For each visible message, fetch the rich body via
+  [`getInboxMessageBody`](../../api/classes/WSAPIInbox.md#getinboxmessagebody)
+  separately. The list type alone is NOT enough to render the title
+  / preview / icon.
+- `onUpdate` fires only when a NEW message is pushed by the server.
+  Mutations (`markRead`, `favorite`, `delete`) do NOT auto-refresh
+  the list — re-call or update local state.
+
+## List view organization
+
+The default Smartico UI presents inbox messages in a **single
+scrollable list** with two filter tabs at the top:
+
+| Tab | Filter |
+|---|---|
+| **All** | No filter — all messages |
+| **Favorite** | `onlyFavorite: true` |
+
+`InboxCategories` (`General` / `Platform` / `Personal`) and
+`InboxReadStatus` are exposed via the SDK but NOT surfaced as tabs in
+the default UI. Custom UIs may add them as additional tabs or filter
+chips.
+
+**Sort order**: server-driven, newest `sent_date` first. No
+client-side re-sort.
+
+**Pagination**: 20 messages per page. For load-more pagination,
+advance `from` by 20 on each subsequent call.
+
+## Item card / row
+
+Fields rendered per row (combining `TInboxMessage` envelope with
+the pre-fetched `TInboxMessageBody`):
+
+| Field | Source | Notes |
+|---|---|---|
+| Icon | `body.icon` (128×128 px) | CSS `background-image`. Fallback to a generic message icon if missing. |
+| Title | `body.title` | Primary text. |
+| Preview | `body.preview_body` | Single-line excerpt. |
+| Sent date | `envelope.sent_date` | Render as relative time ("2h ago", "Yesterday", "12 Jun"). |
+| Unread dot | `envelope.read === false` | Filled colored dot. Hide when read. |
+| Favorite star | `envelope.favorite` | Filled star icon when favorited; outline otherwise. |
+| Delete affordance | hover (desktop) / swipe (mobile) | See "Delete UX". |
+| "Read more" link | shown when `body.html_body` exists | Triggers inline expand. |
+
+**The list needs pre-fetched bodies** — call
+[`getInboxMessageBody`](../../api/classes/WSAPIInbox.md#getinboxmessagebody)
+for each envelope before rendering. The default Smartico UI batches
+these fetches alongside the list. Cache bodies in your application
+state to avoid re-fetching on scroll.
+
+## Detail view / expand
+
+Two rendering modes per device:
+
+- **Mobile / widget**: tap the row → message body expands inline
+  (CSS transition ~0.5 s). The `html_body` (if present) is rendered
+  in a sandboxed iframe with auto-resizing height.
+- **Desktop full-page**: a right-side detail panel renders the
+  selected message; the first message auto-opens.
+
+Detail-view content top-to-bottom:
+
+  1. Icon (larger size).
+  2. Title.
+  3. Either the rich `html_body` (in a sandboxed iframe) OR a
+     formatted `preview_body` block, depending on whether
+     `body.action === 'dp:inbox'`.
+  4. Up to 2 action buttons (`body.buttons`) — only when
+     `action === 'dp:inbox'`.
+  5. Single CTA (when `body.action` is a deep-link / URL other than
+     `'dp:inbox'`).
+
+**Sandbox the iframe**: the `html_body` is operator-supplied content.
+Render via `<iframe srcdoc>` or a sandboxed `<iframe>` to prevent
+script injection into your host page.
+
+## Auto-mark-as-read
+
+The default Smartico UI auto-marks-read when the message detail
+expands (or auto-opens on desktop). Wire it alongside the
+{@link reportImpressionEvent} call so a single user action fires
+both the read mutation and the impression analytic.
+
+If you build a viewport-based "auto-read-on-scroll" instead, set a
+threshold (e.g. row visible in viewport for ≥500 ms) — instant
+mark-on-scroll generates noisy impressions.
+
+## Favorite toggle
+
+Inline star icon click handler:
+
+```ts
+const onToggleFavorite = async (msg: TInboxMessage) => {
+  const target = !msg.favorite;
+  console.log('[smartico] optimistically flip star to', target);
+  const r = await window._smartico.api.markUnmarkInboxMessageAsFavorite(
+    msg.message_guid,
+    target,
+  );
+  if (r.err_code !== 0) {
+    console.error('[smartico] favorite failed — revert local state and show error toast:', r.err_message);
+  }
+};
+```
+
+Show a brief "Added to favorites" / "Removed from favorites" toast
+on success.
+
+## Delete UX
+
+| Trigger | Platform |
+|---|---|
+| Trash-icon click (visible on hover) | Desktop |
+| Swipe left/right past threshold (~75 px) | Mobile |
+| Delete button in detail panel | Desktop full-page |
+
+**No confirm dialog** for single-message delete — the action is
+fast. Animate the row out of the list (~300 ms slide), then call
+{@link deleteInboxMessage}. Show "Message deleted" toast.
+
+For **mark-all** / **delete-all** mutations, surface a confirm dialog
+(those operations are destructive at scale).
+
+## Image / asset specs
+
+| Field | Recommended source | Aspect | Fallback |
+|---|---|---|---|
+| `body.icon` | 128×128 px | 1:1 (square) | Generic message-icon placeholder |
+| `body.html_body` images | (operator-supplied) | (any) | Iframe sandbox handles broken images |
+
+## Empty / loading / error states
+
+- **Loading**: render a skeleton list (5–8 placeholder rows).
+- **Empty (all)**: Lottie animation + "No messages yet…" copy.
+- **Empty (favorite filter active)**: "No favorite messages".
+- **Empty (unread filter active)**: "No unread messages".
+- **Error**: keep prior list visible if any; show non-blocking error
+  banner; retry on next user action.
+
+## Animations / transitions
+
+- **List entry**: stagger fade-in (~30 ms per row) on first render.
+- **New message arrival**: when a push fires `onUpdate`, insert the
+  new row at the top with a slide-in animation (~200 ms).
+- **Detail expand (mobile)**: 0.5 s height transition; iframe height
+  adjusts via ResizeObserver.
+- **Delete**: 300 ms slide-out + height collapse.
+- **Mark-as-read**: unread dot fades from opacity 1 to 0.
+
+## Refresh
+
+`onUpdate` fires ONLY on new-message pushes. After any of the
+mutation methods:
+
+- Update local state optimistically (flip `read`/`favorite`, drop
+  the row from the list).
+- The unread badge auto-updates via
+  [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)'s
+  `core_inbox_unread_count` (push-driven) — no need to manually
+  refresh the count.
+- Re-call `getInboxMessages` only if you need the server-canonical
+  view (e.g. after a long offline period).
+
+## Mobile vs desktop
+
+- **Layout**: mobile is full-width single column with inline detail
+  expand; desktop is 50/50 list + detail split panel.
+- **Detail trigger**: mobile = inline expand; desktop = right
+  panel with auto-open.
+- **Delete**: mobile = swipe; desktop = hover trash-icon.
+- **Favorite**: mobile = always-visible star; desktop =
+  hover-visible.
+
+## Performance
+
+- 20 messages per page keeps payloads small. For very long inboxes,
+  use the load-more pattern rather than fetching everything.
+- Body fetches are CDN HTTP GETs — batch them in parallel using
+  `Promise.all()` for the initial list.
+- Cache message bodies in application state — the SDK does NOT
+  cache them, and re-opening a message would otherwise refetch.