@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/requestMissionClaimReward.md

@@ -0,0 +1,117 @@
+# requestMissionClaimReward — API (TMissionClaimRewardResult)
+
+> Claim the prize for a completed mission.
+> Import: `import { TMissionClaimRewardResult } from '@smartico/public-api'`
+> Search terms: requestMissionClaimReward, missions, TMissionClaimRewardResult
+
+## Signature
+```ts
+_smartico.api.requestMissionClaimReward(mission_id: number, ach_completed_id: number): Promise<TMissionClaimRewardResult>
+```
+
+## Parameters
+- `mission_id` — The mission `ach_id` (from `getMissions()`).
+- `ach_completed_id` — The completion-row identifier, read from `mission.ach_completed_id` on the same mission object fetched via `getMissions()`. Never fabricate or cache across sessions.
+
+## Returns — `Promise<TMissionClaimRewardResult>`
+`TMissionClaimRewardResult`:
+- `err_code` (number) — Error code. `0` = success (rewards credited). See `requestMissionClaimReward` TSDoc for the full table.
+- `err_message` (string) — Optional error message; populated on non-zero `err_code`.
+
+## Behavioral contract
+**Preconditions**
+Only call when, on the mission object from `getMissions()`:
+- `is_completed === true`
+- `requires_prize_claim === true`
+- `prize_claimed_date_ts == null` (i.e. not already claimed)
+- `prize_claim_expiration_date` is `null` OR still in the future
+
+The `ach_completed_id` argument must be passed straight from the same
+mission object (`mission.ach_completed_id`). It is a server-side primary
+key identifying the specific completion row; the SDK consumer should
+never synthesise or cache it across sessions — always re-read it from a
+fresh `getMissions()` result.
+
+
+
+**Recurring missions**
+The server transparently handles both one-shot and recurring mission
+completions. The SDK consumer passes a single `ach_completed_id`
+regardless of mission type; the server resolves the correct completion.
+
+**Refresh after success**
+On any claim response (success OR failure), the SDK automatically
+re-fetches the mission list and fires any `onUpdate` callback
+registered via `getMissions({ onUpdate })`. No manual re-fetch needed.
+Note: points balance, badges, and level state arrive through their
+own push channels — subscribe to them separately if your UI shows
+those values.
+
+**Idempotency**: not idempotent at the row level. A second call on the
+same `ach_completed_id` returns `40017` (already claimed). For a stale
+`ach_completed_id` the second call returns `1`. Guard the call site
+against double-clicks; the SDK does not enforce its own in-flight lock.
+
+**Side effects** (consumer-observable effects of a successful claim):
+- Points credited to the user's balance.
+- CRM-rule activities executed (may grant bonuses, badges; may unlock
+  follow-up missions, which arrive as a later mission auto-refresh).
+- Analytics / automation events fired downstream; not directly observable
+  in the response, but visible via the mission auto-refresh and any
+  subsequent bonus / badge updates.
+
+**UI guidance**: see [UI Guide — `requestMissionClaimReward`](../../docs/ui/missions/UIGuide_requestMissionClaimReward.md).
+
+## Example
+```ts
+const missions = await window._smartico.api.getMissions({
+  onUpdate: (m) => console.log('[smartico] mission list updated — re-render mission UI from this new array', m),
+});
+const mission = missions.find(m => m.ach_id === missionId);
+
+if (
+  !mission ||
+  !mission.is_completed ||
+  !mission.requires_prize_claim ||
+  mission.prize_claimed_date_ts ||
+  (mission.prize_claim_expiration_date && Date.now() >= mission.prize_claim_expiration_date)
+) {
+  console.log('[smartico] claim not applicable — keep claim button hidden');
+  return;
+}
+
+console.log('[smartico] claim starting — show loading spinner on claim button and disable it to prevent double-clicks');
+const r = await window._smartico.api.requestMissionClaimReward(mission.ach_id, mission.ach_completed_id);
+console.log('[smartico] claim response received — clear loading spinner');
+
+if (r.err_code === 0 || r.err_code === 40017) {
+  console.log('[smartico] claim succeeded (or was already claimed) — points/bonuses are credited; mission list auto-refresh will fire via the onUpdate above; hide the claim button');
+} else if (r.err_code === 40015) {
+  console.error('[smartico] claim window expired — show a "claim period ended" message and remove the claim button:', mission.prize_claim_expiration_date);
+} else if (r.err_code === 40016) {
+  console.error('[smartico] mission reported as not completed by server — local state was stale; auto-refresh will reconcile, do not retry');
+} else {
+  console.error('[smartico] claim failed — show an error toast with this message to the user (and re-fetch missions to recover from a stale ach_completed_id):', r.err_message);
+}
+```
+
+## Errors
+**Error codes** (in `err_code`)
+- `0` — success; the prize was claimed and rewards have been credited.
+- `1` — generic server error. Covers several distinct underlying
+  conditions, all collapsed into the same code: stale or wrong
+  `ach_completed_id` (does not match user / mission), the mission no
+  longer requiring a prize claim, the mission being archived/draft,
+  label mismatch, or the completion being too old (server enforces a
+  freshness window of several months). Recovery: re-fetch missions
+  with `getMissions()`; if the mission still appears claimable,
+  surface a generic error.
+- `40015` — claim window expired (`prize_claim_expiration_date` has
+  passed). Show a "claim period ended" message; do not retry.
+- `40016` — mission is not completed yet. Indicates a race or a stale
+  local cache. Re-fetch via `getMissions()`; if `is_completed` is still
+  false, the UI should hide the claim button.
+- `40017` — prize already claimed. Treat as idempotent success: refresh
+  the mission list (auto-refresh will fire) and hide the claim button.
+  Usually means another tab/session already claimed it.
+- other non-zero — generic server error. Surface `err_message` if any.

package/docs/capabilities/requestMissionOptIn.md

@@ -0,0 +1,98 @@
+# requestMissionOptIn — API (TMissionOptInResult)
+
+> Opt the current user in to a mission.
+> Import: `import { TMissionOptInResult } from '@smartico/public-api'`
+> Search terms: requestMissionOptIn, missions, TMissionOptInResult, err_code, err_message
+
+## Signature
+```ts
+_smartico.api.requestMissionOptIn(mission_id: number): Promise<TMissionOptInResult>
+```
+
+## Parameters
+- `mission_id` — The mission `id` (from `getMissions()`)
+
+## Returns — `Promise<TMissionOptInResult>`
+`TMissionOptInResult`:
+- `err_code` (number) — Error code. `0` = success. See `requestMissionOptIn` TSDoc for the full table.
+- `err_message` (string) — Optional error message; populated on non-zero `err_code`.
+
+## Behavioral contract
+**Preconditions**
+Only call when the mission has `is_requires_optin === true`,
+`is_opted_in === false`, and `is_locked === false`. Calling on a
+mission that does not require opt-in is wasted; calling twice returns
+`40010`.
+
+
+
+**Time-limited missions**
+For missions with `time_limit_ms > 0`, the countdown begins at opt-in
+time, not at mission creation. Server records expiration as
+`optin_date + time_limit_ms`.
+
+**Refresh after success**
+The SDK refreshes its mission cache automatically on opt-in response;
+any `onUpdate` callback passed to a prior `getMissions({ onUpdate })`
+fires with the new state shortly after. No manual re-fetch needed.
+
+**Idempotency**: not idempotent. A second call returns `40010`. Guard
+the call site against double-clicks.
+
+**Side effects**: does NOT award points / badges / levels directly.
+Rewards come from task completion, which is itself gated on opt-in.
+May affect visibility of other missions whose visibility conditions
+depend on this opt-in.
+
+**UI guidance**: see [UI Guide — `requestMissionOptIn`](../../docs/ui/missions/UIGuide_requestMissionOptIn.md).
+
+**Visitor mode: not supported**
+
+## Example
+```ts
+const missions = await window._smartico.api.getMissions({
+  onUpdate: (m) => console.log('[smartico] mission list updated — re-render mission UI from this new array', m),
+});
+const mission = missions.find(m => m.id === missionId);
+
+if (!mission || !mission.is_requires_optin || mission.is_opted_in || mission.is_locked) {
+  console.log('[smartico] opt-in not applicable — keep UI as-is');
+  return;
+}
+
+console.log('[smartico] opt-in starting — show loading spinner on opt-in button and disable it to prevent double-clicks');
+const r = await window._smartico.api.requestMissionOptIn(mission.id);
+console.log('[smartico] opt-in response received — clear loading spinner');
+
+if (r.err_code === 0 || r.err_code === 40010) {
+  console.log('[smartico] opt-in succeeded (or was already done) — onUpdate above will fire with refreshed mission state; no manual re-fetch needed');
+} else if (r.err_code === 40014) {
+  console.error('[smartico] mission is locked — surface the unlock description as guidance:', mission.unlock_mission_description);
+} else {
+  console.error('[smartico] opt-in failed — show an error toast with this message to the user:', r.err_message);
+}
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+{
+  "err_code": 0,
+  "err_message": ""
+}
+```
+
+## Errors
+**Error codes** (in `err_code`)
+- `0` — success; task progress counting begins
+- `105` — wrong mission id (different label) OR visibility conditions
+  not met. Same code covers both; use `err_message` to disambiguate.
+- `40010` — already opted-in. Safe to treat as "no-op success"; usually
+  means local mission state was stale (e.g. user opted in from another
+  session/tab).
+- `40013` — mission not opt-in-able: missing `requires_optin`, in
+  DRAFT/ARCHIVED state, or outside its `active_from_ts` /
+  `active_till_ts` window.
+- `40014` — mission is locked; user has unlock-tasks remaining.
+  Surface the mission's `unlock_mission_description` to guide them.
+- other non-zero — generic server error. Surface `err_message` if any.

package/docs/capabilities/requestRaffleOptin.md

@@ -0,0 +1,108 @@
+# requestRaffleOptin — API (TRaffleOptinResponse)
+
+> Opts the current user into a specific raffle draw run.
+> Import: `import { TRaffleOptinResponse } from '@smartico/public-api'`
+> Search terms: requestRaffleOptin, raffles, TRaffleOptinResponse
+
+## Signature
+```ts
+_smartico.api.requestRaffleOptin(props: { raffle_id: number; draw_id: number; raffle_run_id: number }): Promise<TRaffleOptinResponse>
+```
+
+## Parameters
+- `props.raffle_id` — The parent raffle's `id`.
+- `props.draw_id` — The draw's schedule_id (`TRaffleDraw.id`).
+- `props.raffle_run_id` — The run instance ID (`TRaffleDraw.run_id`).
+
+## Returns — `Promise<TRaffleOptinResponse>`
+`TRaffleOptinResponse`:
+- `err_code` (number) — Error code. `0` = success. See `requestRaffleOptin` TSDoc for the full table.
+- `err_message` (string) — Optional error message; populated on non-zero `err_code`.
+
+## Behavioral contract
+**Preconditions**
+Read the candidate draw from `getRaffles`'s embedded
+`draws[]` and gate the call on
+`requires_optin === true && !user_opted_in && is_active &&
+current_state !== Executed`. Calling without these guards may
+return a non-zero `err_code`.
+
+**Argument mapping** — the three IDs come from different fields:
+- `raffle_id` — the parent raffle's `TRaffle.id`
+- `draw_id` — `TRaffleDraw.id` (schedule_id, stable across runs)
+- `raffle_run_id` — `TRaffleDraw.run_id` (instance ID for this
+ specific run)
+
+
+
+**Idempotency**: NOT idempotent. A second call on the same
+`raffle_run_id` returns `err_code === 1` with `err_message`
+indicating the user is already opted in. Treat as success in
+the UI — the underlying state is what the consumer wants.
+Guard the call site against double-clicks.
+
+**Refresh after success (and after failure)**
+The SDK automatically refreshes the raffles cache on every
+response and fires the `onUpdate` callback registered via
+`getRaffles`. After `err_code === 0`, the affected draw's
+`user_opted_in` flips to `true` on the refreshed list.
+
+**Side effects** (on `err_code === 0`)
+- The user is registered for this run. Tickets earned within
+ the run's eligibility window will participate in the draw.
+- No balance change. No CRM-side rewards. Opt-in is a metadata
+ operation only.
+
+**Throws**
+`raffle_id`, `draw_id`, and `raffle_run_id` are all required —
+the SDK throws synchronously when any is missing or falsy.
+
+**UI guidance**: see [UI Guide — `requestRaffleOptin`](../../docs/ui/raffles/UIGuide_requestRaffleOptin.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const raffles = await window._smartico.api.getRaffles({
+  onUpdate: (refreshed) => console.log('[smartico] raffles refreshed — re-render', refreshed),
+});
+const raffle = raffles[0];
+const draw = raffle.draws.find(d =>
+  d.requires_optin && !d.user_opted_in && d.is_active && d.current_state !== 3
+);
+
+if (!draw) {
+  console.log('[smartico] no opt-in-required draw available — keep CTA hidden');
+  return;
+}
+
+console.log('[smartico] opt-in starting — set in-flight flag, show loading dots on the Opt-in button');
+const r = await window._smartico.api.requestRaffleOptin({
+  raffle_id: raffle.id,
+  draw_id: draw.id,        // schedule_id, NOT run_id
+  raffle_run_id: draw.run_id,
+});
+console.log('[smartico] opt-in response received — clear in-flight flag');
+
+if (r.err_code === 0) {
+  console.log('[smartico] opted in successfully — show "Fully opted in" state on the draw card; onUpdate above will fire with user_opted_in: true');
+} else if (r.err_code === 1 && r.err_message?.toLowerCase().includes('already opted in')) {
+  console.log('[smartico] already opted in (perhaps from another tab) — treat as success, show "Fully opted in"');
+} else {
+  console.error('[smartico] opt-in failed — surface this error to the user:', r.err_message);
+}
+```
+
+## Errors
+**Error codes** (in `err_code`)
+- `0` — success; the user is opted into this run. Tickets
+ collected after the run's `ticket_start_ts` will participate.
+- `1` — generic opt-in failure. The `err_message` distinguishes
+ the specific cause: the draw doesn't require opt-in
+ (`requires_optin === false`), `raffle_id` doesn't match the
+ `draw_id`, the user is already opted in (or the draw has
+ completed), or the user is in a control group for this raffle.
+- other non-zero — generic server error. Surface `err_message`.
+
+## Related
+- `getRaffles`

package/docs/capabilities/setAvatar.md

@@ -0,0 +1,132 @@
+# setAvatar — API (TSetAvatarResult)
+
+> Activates the specified avatar for the current user.
+> Import: `import { TSetAvatarResult } from '@smartico/public-api'`
+> Search terms: setAvatar, avatars, TSetAvatarResult, err_code, err_message
+
+## Signature
+```ts
+_smartico.api.setAvatar(props: { avatar_url: string; avatar_real_id: number }): Promise<TSetAvatarResult>
+```
+
+## Parameters
+- `props.avatar_url` — Absolute CDN URL of the avatar image. Read from `TAvatarDefinition.url` for catalog avatars or `TAvatarCustomized.url` for AI variants.
+- `props.avatar_real_id` — Numeric ID of the base avatar from `TAvatarDefinition.avatar_real_id`. For AI variants, this is the `avatar_real_id` of the base they were derived from.
+
+## Returns — `Promise<TSetAvatarResult>`
+`TSetAvatarResult`:
+- `err_code` (number) — Error code. `0` = success. See `setAvatar` TSDoc for the full table.
+- `err_message` (string) — Optional error message; populated on non-zero `err_code`.
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode is not supported.
+- `avatar_url` must be non-empty and `avatar_real_id` must be truthy — the SDK
+ throws synchronously otherwise (the request never reaches the server).
+- The avatar must exist in the catalog from `getAvatarsList` (or be an AI
+ variant of a base avatar the user already owns). Free avatars
+ (`avatar_source_type_id === 0`) and the user's currently active avatar bypass the
+ ownership check; all others require `is_given === true`.
+
+
+
+**Refresh after success**
+- The SDK clears both the `getAvatarsList` and `getAvatarsCustomized` caches —
+ the next call to either returns fresh data with the new `is_in_use` flag set on
+ the chosen avatar.
+- The server persists the new avatar URL on the user record; `getUserProfile`
+ reflects it on the next read in this session.
+- **No push to other open sessions.** A second device / tab the user is logged in
+ on will not see the new avatar until it next calls `getUserProfile` or
+ re-identifies. Plan UI accordingly.
+
+**Idempotency**: safe to retry. Re-applying the same `avatar_real_id` returns
+`err_code: 0` and produces no double side effects (no double-deduction — this
+method does not charge any currency — and no duplicate log entries).
+
+**Side effects**: updates the user's stored `avatar_id` / `avatar_real_id`. Does
+NOT cost points, gems, or diamonds — the cost lives on the separate AI
+customization HTTP flow (`getAvatarPrompts`). Does NOT write a user-visible
+entry to `getActivityLog`.
+
+**UI guidance**: see [UI Guide — `setAvatar`](../../docs/ui/avatars/UIGuide_setAvatar.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const avatars = await window._smartico.api.getAvatarsList();
+const target = avatars.find((a) => a.avatar_real_id === 7);
+
+if (!target) {
+    console.error('[smartico] avatar 7 not in catalog — hide the picker entry');
+    return;
+}
+
+const isLocked = !target.is_given && target.avatar_source_type_id !== 0;
+if (isLocked) {
+    console.log('[smartico] avatar is locked — show "earn this first" prompt instead of calling setAvatar');
+    return;
+}
+
+const r = await window._smartico.api.setAvatar({
+    avatar_url:     target.avatar_url,
+    avatar_real_id: target.avatar_real_id,
+});
+
+switch (r.err_code) {
+    case 0:
+        console.log('[smartico] avatar applied — close picker, refresh header avatar');
+        break;
+    case 1:
+        console.error('[smartico] avatar not in catalog — refresh catalog and show error');
+        break;
+    case 2:
+        console.error('[smartico] avatar inactive — operator disabled it; hide from picker');
+        break;
+    case 3:
+        console.error('[smartico] outside time window — show "available on X" message');
+        break;
+    case 4:
+        console.error('[smartico] not owned — show unlock requirements');
+        break;
+    default:
+        console.error('[smartico] avatar apply failed — show generic error toast:', r.err_message);
+}
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+{
+  "err_code": 4,
+  "err_message": "Avatar is not available"
+}
+```
+
+## Errors
+**Error codes** (in `err_code`)
+- `0` — success; cache is cleared and the profile avatar updates immediately.
+- `1` — avatar not found in the catalog. The `avatar_real_id` doesn't exist for
+ this label.
+- `2` — avatar inactive (deactivated by the operator).
+- `3` — outside the avatar's active time window
+ (`active_from_date` / `active_till_date`).
+- `4` — user does not own this avatar (it isn't in their `is_given` set and isn't
+ a free / default avatar).
+- other non-zero — generic server error; surface `err_message` if present.
+
+The default Smartico UI shows a hardcoded "Failed to apply avatar" toast on any
+non-zero `err_code` and does not surface `err_message`. Custom UIs SHOULD branch
+on the code and prefer `err_message` when present (it is the localized server
+string).
+
+## Related
+- `getUserProfile`
+- `TAvatarDefinition.url`
+- `TAvatarCustomized.url`
+- `getAvatarsList`
+- `getAvatarPrompts`
+- `getActivityLog`
+- `TAvatarDefinition.avatar_real_id`
+- `TSetAvatarResult`

package/docs/capabilities/smarticoCallbacks.md

@@ -0,0 +1,165 @@
+# _smartico.on — events & callbacks
+
+> _smartico.on — events & callbacks.
+> Search terms: on, off, callbacks, events, subscribe, subscribeUpdate, onWin, onReady, props_change, identify, EXTERNAL_CALLBACK, lifecycle, _smartico.on
+
+Beyond the request/response `_smartico.api.*` methods, the SDK emits **lifecycle
+and engagement events** you can subscribe to. Register a handler with
+`_smartico.on(...)` and it fires whenever that event occurs — user identified,
+balance changed, gamification widget opened, mini-game won, jackpot hit, etc.
+
+This is the push side of the SDK: instead of polling, you react to events as
+they happen.
+
+## Registering and removing handlers
+
+```js
+// Subscribe (works after smartico.js has loaded)
+_smartico.on('identify', (errCode, props) => {
+  console.log('[smartico] user identified — render the logged-in UI');
+});
+
+// The queue form also works BEFORE the library finishes loading — the call
+// is queued and replayed once smartico.js is ready. Use this when wiring
+// handlers in your page <head> before the script loads.
+_smartico('on', 'identify', (errCode, props) => { /* ... */ });
+
+// Remove a specific handler
+function onProps(props) { /* ... */ }
+_smartico.on('props_change', onProps);
+_smartico.off('props_change', onProps);
+
+// Passing null removes ALL handlers registered for that key
+_smartico.on('props_change', null);
+```
+
+### Behavior
+
+- **Multiple handlers per event stack.** Calling `on` repeatedly for the same
+  key adds handlers; they all fire. Use `off(key, fn)` to remove one, or
+  `on(key, null)` to clear all for that key.
+- **Handlers fire asynchronously** (on the next tick) and are isolated — a
+  handler that throws logs a warning and does NOT prevent the other handlers
+  (or the SDK) from running. Don't rely on execution order between handlers.
+- **Works in both authenticated and visitor mode.** A handler registered via
+  `_smartico.on(...)` is active whether the session is a logged-in user or a
+  visitor (`_smartico.vapi(...)`). Events that require an account (`identify`,
+  `login`, `logout`) simply never fire in visitor mode — see the per-event
+  notes below.
+- **Late subscription misses past events.** `on` does not replay events that
+  already happened. If you subscribe to `init` after the library has already
+  initialized, your handler won't be called. For one-time lifecycle events
+  (`init`, `identify`), register early (use the `_smartico('on', ...)` queue
+  form in your page head).
+
+## Event reference
+
+The first argument of `_smartico.on(...)` is the event key — one of the
+strings below.
+
+### Lifecycle
+
+| Event key | Fires when | Handler arguments |
+|---|---|---|
+| `init` | The SDK has finished loading and initializing. Fires shortly after `_smartico.init(...)`, **before** the user is identified. | `(errCode)` — `0` on success |
+| `label_init_completed` | The label configuration / settings have loaded (the handshake that follows `init`). At this point gamification products are known. | `(errCode, message)` |
+| `identify` | A user identify attempt completes — **both success and failure**. Branch on `errCode`. | `(errCode, props, message)` on success; `(errCode, {})` on failure. Not fired in visitor mode. |
+| `login` | A login completes successfully. | `()` — no arguments. Not fired in visitor mode. |
+| `logout` | A logout completes successfully. | `()` — no arguments. Not fired in visitor mode. |
+
+### User state
+
+| Event key | Fires when | Handler arguments |
+|---|---|---|
+| `props_change` | Any public user property changes — points, level, balances (gems/diamonds), avatar, unread inbox count, nickname, etc. Fires once right after identify with the full initial set, then again on each change with the changed subset. | `(props)` — a partial public-properties object containing the changed fields. `avatar_id` is returned as a fully-qualified URL. |
+| `page_navigation` | A page load or SPA route change is detected. | `({ url, prev_url, referrer, source })` — `source` is `'load'` (initial page load) or the navigation trigger. |
+| `session_based_dp_detected` | A deep link stored earlier in the browser session is detected after identify (and is about to be executed). | `()` — no arguments. |
+
+### Gamification widget lifecycle
+
+| Event key | Fires when | Handler arguments |
+|---|---|---|
+| `gf_starting` | The main gamification widget begins opening (e.g. the user taps the gamification entry point or a deep link opens it). | `()` |
+| `gf_started` | The gamification widget has rendered and is displayed to the user. Fires after `gf_starting`. | `()` |
+| `gf_closing` | The gamification widget (or a standalone mini-game) begins closing. | `()` |
+| `saw_starting` | A standalone mini-game surface (Spin-a-Wheel / MatchX / Quiz) begins opening. | `()` |
+| `inbox_starting` | The standalone inbox widget begins opening. | `()` |
+| `gf_ux` | A screen-view / UX analytics event occurs inside the gamification widget (the user navigates to a screen or section). Use to mirror in-widget navigation into your own analytics. | `({ screen_name_id, custom_section_id, entity_id, screen_subname_id })` |
+
+### Wins and game launches
+
+| Event key | Fires when | Handler arguments |
+|---|---|---|
+| `mini_game_win` | A mini-game spin finishes and a prize is determined. Fires for both real and visitor-mode plays. | `({ prize_id, name, visitor_win_uuid })` — `name` is the prize display name. In visitor mode, `visitor_win_uuid` can be passed to `_smartico.convertVisitorGame(uuid)` to attach the win to a real account on registration. |
+| `jackpot_win` | A jackpot the user participates in is hit (the pot explodes and the user is among the recipients). | `(message)` — the win payload (winner details + jackpot info). See the Jackpots UI guide (`docs/ui/jackpots/`) for how the default Smartico UI surfaces wins. |
+| `ach_game_opening` | The user taps a related / eligible casino game tile from inside the gamification widget (mission, tournament, jackpot, or store context). Use this to launch the game in your own casino lobby. | `(game)` — the game object (catalog id, name, launch links, plus a `context` field naming where it was opened from). If you do not handle this event, the default Smartico UI opens the game's configured link itself. |
+
+### Errors
+
+| Event key | Fires when | Handler arguments |
+|---|---|---|
+| `protocol_error` | The server rejected a request as an unsupported command (a protocol-level error, distinct from a method's `err_code`). | `({ errCode, errMsg })` |
+
+## Examples
+
+### Keep a balance widget live
+
+```js
+// Render once on identify, then patch on every change.
+_smartico.on('identify', (errCode, props) => {
+  if (errCode === 0) {
+    console.log('[smartico] initial balance — render widget:', props.ach_points_balance);
+  } else {
+    console.error('[smartico] identify failed — show logged-out state');
+  }
+});
+
+_smartico.on('props_change', (props) => {
+  if (props.ach_points_balance !== undefined) {
+    console.log('[smartico] points changed — update the balance widget:', props.ach_points_balance);
+  }
+  if (props.core_inbox_unread_count !== undefined) {
+    console.log('[smartico] unread count changed — update the inbox badge:', props.core_inbox_unread_count);
+  }
+});
+```
+
+### React to a mini-game win
+
+```js
+_smartico.on('mini_game_win', ({ prize_id, name, visitor_win_uuid }) => {
+  console.log('[smartico] user won prize', prize_id, '—', name, '— show your own celebration overlay');
+
+  if (visitor_win_uuid) {
+    console.log('[smartico] visitor win — after the user registers, call _smartico.convertVisitorGame to attach this win');
+  }
+});
+```
+
+### Launch casino games from the gamification widget yourself
+
+```js
+// Take over game launching so games open in your lobby instead of the
+// default link-open behavior.
+_smartico.on('ach_game_opening', (game) => {
+  console.log('[smartico] user wants to play game — launch it in your lobby:', game.ext_game_id, '(context:', game.context + ')');
+});
+```
+
+### Mirror in-widget navigation into your analytics
+
+```js
+_smartico.on('gf_ux', ({ screen_name_id, custom_section_id, entity_id }) => {
+  console.log('[smartico] gamification screen view — forward to your analytics:', screen_name_id, custom_section_id, entity_id);
+});
+```
+
+## Notes
+
+- The handler argument shapes above describe what the SDK passes today. Treat
+  unfamiliar fields defensively (optional-chain / null-check) — payloads can
+  gain fields over time.
+- For request/response data (the current list of missions, the user profile,
+  the jackpot pots, etc.), use the `_smartico.api.*` methods (see the API
+  reference). Callbacks are for reacting to events; the API methods are for
+  fetching and mutating state.