@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/getUserLevelExtraCounters.md

@@ -0,0 +1,92 @@
+# getUserLevelExtraCounters — API (UserLevelExtraCountersT)
+
+> Returns the user's current values for the two label-defined "extra counters" used by sliding-window leveling logic.
+> Import: `import { UserLevelExtraCountersT } from '@smartico/public-api'`
+> Search terms: getUserLevelExtraCounters, user, UserLevelExtraCountersT, level_counter_1, level_counter_2
+
+## Signature
+```ts
+_smartico.api.getUserLevelExtraCounters(): Promise<UserLevelExtraCountersT>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<UserLevelExtraCountersT>`
+`UserLevelExtraCountersT`:
+- `level_counter_1` (number) — Current value of the user's first level counter. Operator-defined semantics per label. `undefined` on points-only labels.
+- `level_counter_2` (number) — Current value of the user's second level counter. Operator-defined semantics per label. `undefined` on points-only labels.
+
+## Behavioral contract
+**When this matters**
+Only labels configured for sliding-window leveling populate the
+counter fields. On the default points-only leveling model, both
+`level_counter_1` and `level_counter_2` are `undefined`. Detect
+a points-only label by either counter being `undefined`.
+
+**Counter semantics — operator-defined**
+The SDK exposes raw numeric values; the meaning of each counter
+(deposit amount, wager amount, lifetime spend, etc.) is fully
+operator-defined per label. Resolve labels for display via
+`getTranslations` — the operator's display strings are
+stored under the translation keys `levelsCounter1Name` and
+`levelsCounter2Name`.
+
+**Refresh cadence**
+Sliding-window counters are recomputed by a periodic server-side
+job. Its rebuild cadence is operator-configured per brand —
+commonly daily, though it can be set more frequent — so level
+transitions driven by counter changes surface with a latency tied
+to that rebuild schedule after the underlying activity (e.g. a
+deposit), not in real time.
+
+**Idempotency**: safe. Read-only. Repeated calls within the cache
+window return a deep-cloned cached value without a network
+round-trip.
+
+**Side effects**: none — pure read.
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const [counters, levels, profile] = await Promise.all([
+  window._smartico.api.getUserLevelExtraCounters(),
+  window._smartico.api.getLevels(),
+  Promise.resolve(window._smartico.api.getUserProfile()),
+]);
+
+// Quick detection: undefined means this label doesn't use sliding-window leveling.
+if (counters.level_counter_1 === undefined) {
+  console.log('[smartico] points-only label — skip counter UI; show points progress only');
+  return;
+}
+
+// Find the next level and render a 3-bar progress block.
+const currentIdx = levels.findIndex(l => l.id === profile.ach_level_current_id);
+const next = levels[currentIdx + 1];
+if (next) {
+  console.log('[smartico] render points bar:', profile.ach_points_ever, '/', next.required_points);
+  if (next.required_level_counter_1) {
+    console.log('[smartico] render counter 1 bar:', counters.level_counter_1, '/', next.required_level_counter_1);
+  }
+  if (next.required_level_counter_2) {
+    console.log('[smartico] render counter 2 bar:', counters.level_counter_2, '/', next.required_level_counter_2);
+  }
+}
+```
+
+### 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
+{
+  "level_counter_1": null,
+  "level_counter_2": null
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getLevels`

package/docs/capabilities/getUserProfile.md

@@ -0,0 +1,184 @@
+# getUserProfile — API (TUserProfile)
+
+> Returns the current user's public profile — the source of truth for balances (points / gems / diamonds), the current level ID, the display username + avatar, language, public tags, and the inbox unread count.
+> Import: `import { TUserProfile } from '@smartico/public-api'`
+> Search terms: getUserProfile, user, getPublicProps, getProfile, balance, points, TUserProfile, core_public_tags, ach_points_ever, core_clan_is_kicked, user_last_session_push_state, aff_referred_by_friend_ext_user_id, core_inbox_unread_count, core_user_language, ach_level_current
+
+## Signature
+```ts
+_smartico.api.getUserProfile(): TUserProfile
+```
+
+## Parameters
+_None._
+
+## Returns — `TUserProfile`
+`TUserProfile`:
+- `core_user_language` (string) — Language code stored server-side for the user (e.g. `"en"`, `"de"`).
+- `ach_points_balance` (number) — Current spendable points balance — decremented by store purchases, tournament buy-ins, and clan entry fees.
+- `ach_points_ever` (number) — All-time cumulative points earned. Monotonic — NOT decremented by store purchases or clan/tournament fees.
+- `ach_gems_balance` (number) — Current gems balance (secondary currency).
+- `ach_diamonds_balance` (number) — Current diamonds balance (tertiary currency).
+- `core_public_tags` (string[]) — Server-stored public tags on the user (uppercase strings). Modify via `_smartico.updatePublicTags(operation, tags)`.
+- `ach_level_current_id` (number) — FK into the level ladder; resolve via `getCurrentLevel()` or `getLevels()`.
+- `core_is_test_account` (boolean) — `true` when the user is flagged as a test account.
+- `avatar_url` (string) — Resolved CDN URL for the user's avatar.
+- `public_username` (string) — Display username (operator-defined alias).
+- `core_inbox_unread_count` (number) — Unread inbox messages count. Push-updated in real time.
+- `core_recommended_deposit_amount` (number) — AI-recommended deposit amount for this user. Undefined when no recommendation is currently available.
+- `core_recommended_casino_bet_amount` (number) — AI-recommended casino bet amount for this user. Undefined when no recommendation is currently available.
+- `ach_level_current` (string) — Display name of the user's current level (e.g. `"Silver"`); resolve the id via `getCurrentLevel()`.
+- `ach_gamification_in_control_group` (boolean) — `true` when the user is in the gamification A/B control group (gamification UI suppressed).
+- `user_id` (number) — Smartico-internal numeric user id.
+- `user_country` (string) — ISO country code of the user (e.g. `"BG"`).
+- `core_wallet_currency` (string) — Wallet currency code (e.g. `"EUR"`).
+- `core_registration_date` (number) — Registration timestamp (epoch ms); `0` when unknown.
+- `user_last_session_push_state` (string) — Last-session browser push-permission state (e.g. `"BLOCKED"`, `"GRANTED"`).
+- `acc_bonus_abuser` (boolean) — `true` when the account is flagged as a bonus abuser.
+- `avatar_id` (string) — Selected avatar id (catalogue avatar or AI-variant base).
+- `avatar_real_id` (number) — `avatar_real_id` of the selected avatar; `0` when none.
+- `core_avatar_real_id` (number | null) — `avatar_real_id` of the user's core avatar; null when unset.
+- `core_clan_id` (string) — Current clan id (string); empty/null when not in a clan.
+- `core_clan_is_kicked` (boolean | null) — `true` when the user was kicked from their clan; null when not applicable.
+- `core_clan_kicked_out_id` (number | null) — Id of the clan the user was kicked from; null when not applicable.
+- `aff_referred_by_friend_ext_user_id` (string | null) — ext_user_id of the friend who referred this user; null when none.
+- `aff_refer_friend_url` (string | null) — Refer-a-friend share URL; null when the feature is disabled.
+- `aff_refered_friends_count` (number) — Count of friends this user has referred.
+
+## Behavioral contract
+**Preconditions**
+The tracker must be initialised — calling this before the identify
+round-trip completes throws (`"Tracker is not initialized, cannot
+getUserProfile"`). Safe ways to wait for readiness:
+- register `_smartico.on('identify', (errCode, props) => ...)` —
+ fires once after a successful identify with the full props
+- register `_smartico.on('props_change', () => ...)` — fires first
+ at identify with the full snapshot, then on every push update
+
+**What's kept live (push-updated)**
+Balance fields (`ach_points_balance`, `ach_gems_balance`,
+`ach_diamonds_balance`, `ach_points_ever`), `ach_level_current_id`,
+`core_public_tags`, `core_inbox_unread_count`, `core_user_language`,
+`avatar_url`, `public_username`, and the AI-driven recommended-amount
+fields all flow over the SDK's user-properties update channel as
+partial updates — the snapshot is patched in place when any of them
+change server-side. Re-call `getUserProfile()` (or watch
+`props_change`) to observe new values.
+
+**Reading state from the returned profile**
+Balances (`ach_points_balance`, `ach_gems_balance`,
+`ach_diamonds_balance`) are the canonical source for affordability
+checks across the SDK — compare against `entry_fee_amount` (clans),
+`registration_cost_points` / `_gems` / `_diamonds` (tournaments), and
+`price` / `discounted_price` + `purchase_type` (store items).
+`ach_points_ever` is monotonic — store purchases deduct from
+`ach_points_balance` but NEVER from `ach_points_ever`, so it remains
+useful for level-progress math (`required_points` on the next
+`getLevels` entry minus `ach_points_ever`). `ach_level_current_id`
+is the FK into the level ladder — resolve metadata via
+`getCurrentLevel` (richer, includes progress %) or
+`getLevels` (full ladder lookup table).
+
+**Inbox unread count** — `core_inbox_unread_count` on this profile
+is push-updated in real time (under 1 second). For an inbox badge,
+prefer this field over `getInboxUnreadCount` (which is cached
+for 30 s) — same value, fresher signal.
+
+**Language**: `core_user_language` reflects the server's stored
+language. If the consumer just called `_smartico.changeLanguage(...)`,
+the field may briefly lag the local intent until the server push
+arrives. Use `_smartico.getPublicProps()` for the
+client-fallback-applied version if instant accuracy matters.
+
+**Idempotency / Side effects**: trivially safe — no network call,
+no state mutation.
+
+**UI guidance**: see [UI Guide — `getUserProfile`](../../docs/ui/user/UIGuide_getUserProfile.md).
+
+**Visitor mode**: not supported — throws. Visitor sessions do not
+have a public-profile snapshot.
+
+## Example
+```ts
+// Wait for identify before calling.
+window._smartico.on('identify', (errCode) => {
+  if (errCode !== 0) return;
+  const profile = window._smartico.api.getUserProfile();
+  console.log('[smartico] initial profile loaded — render the user widget:', profile);
+});
+
+// Stay in sync with live updates.
+window._smartico.on('props_change', (changed) => {
+  // `changed` is the partial keys for this push (full snapshot at identify).
+  const profile = window._smartico.api.getUserProfile();
+  console.log('[smartico] profile updated — re-render any widgets bound to:', Object.keys(changed),
+    '— balances now:', profile.ach_points_balance, profile.ach_gems_balance, profile.ach_diamonds_balance);
+
+  // React to specific fields.
+  if ('ach_level_current_id' in changed) {
+    console.log('[smartico] level changed — call getCurrentLevel() for richer detail, animate the level badge');
+  }
+  if ('core_inbox_unread_count' in changed) {
+    console.log('[smartico] inbox unread count changed — update the badge to:', profile.core_inbox_unread_count);
+  }
+});
+
+// Affordability gating example — used inside a clan / tournament / store CTA handler.
+const profile = window._smartico.api.getUserProfile();
+const item = await window._smartico.api.getStoreItems().then(items => items[0]);
+const price = item.discounted_price ?? item.price;
+const balance = {
+  points: profile.ach_points_balance,
+  gems: profile.ach_gems_balance,
+  diamonds: profile.ach_diamonds_balance,
+}[item.purchase_type];
+if (balance < price) {
+  console.log('[smartico] insufficient', item.purchase_type, '— disable Buy and show deficit', price - balance);
+}
+```
+
+### 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
+{
+  "core_public_tags": [
+    "SMARTICO.DEV"
+  ],
+  "ach_points_ever": 690,
+  "core_clan_is_kicked": null,
+  "user_last_session_push_state": "BLOCKED",
+  "aff_referred_by_friend_ext_user_id": null,
+  "core_inbox_unread_count": 0,
+  "core_user_language": "EN",
+  "ach_level_current": "Silver",
+  "ach_gems_balance": 10,
+  "ach_level_current_id": 698,
+  "user_country": "BG",
+  "ach_points_balance": 326,
+  "core_registration_date": 0,
+  "core_recommended_deposit_amount": 0,
+  "core_recommended_casino_bet_amount": 0,
+  "ach_gamification_in_control_group": false,
+  "core_avatar_real_id": null,
+  "core_wallet_currency": "UNKNOWN",
+  "ach_diamonds_balance": 1,
+  "aff_refer_friend_url": null,
+  "acc_bonus_abuser": false,
+  "aff_refered_friends_count": 0,
+  "core_clan_kicked_out_id": null,
+  "core_clan_id": "",
+  "core_is_test_account": false,
+  "user_id": 361368543,
+  "avatar_id": "https://cdn.example/avatars/12/00000000-0000-0000-0000-000000000000.png",
+  "avatar_real_id": 12,
+  "public_username": "Antonio",
+  "avatar_url": "https://cdn.example/avatars/12/00000000-0000-0000-0000-000000000000.png"
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getLevels`
+- `getCurrentLevel`

package/docs/capabilities/jackpotGet.md

@@ -0,0 +1,173 @@
+# jackpotGet — API (JackpotDetails)
+
+> Returns the user-eligible jackpots active for the label, fused with their live pot values.
+> Import: `import { JackpotDetails } from '@smartico/public-api'`
+> Search terms: jackpotGet, jackpots, JackpotDetails, JackpotType, JackpotPublicMeta, JackpotHtmlTemplate, JackpotContributionType, JackpotPot, JackPotTemparature, jp_template_id, jp_type_id, jp_public_meta, jp_currency, user_currency, related_games, contribution_type, contribution_value
+
+## Signature
+```ts
+_smartico.api.jackpotGet(filter?: { related_game_id?: string; jp_template_id?: number }): Promise<JackpotDetails[]>
+```
+
+## Parameters
+- `filter` — Optional filter narrowing the result set.
+- `filter.related_game_id` — Limit to jackpots linked to this game ID (from the operator's games catalog).
+- `filter.jp_template_id` — Limit to a single template.
+
+## Returns — `Promise<JackpotDetails[]>`
+Array of `JackpotDetails`. Each item:
+- `jp_template_id` (number) — Stable numeric ID of the template; pass to opt-in / opt-out / winners / eligible-games methods.
+- `jp_type_id` (JackpotType) — Whether the jackpot has a shared pot or one independent per user; see `JackpotType`.
+- `jp_public_meta` (JackpotPublicMeta) — Display data: name, description, image_url, winner / not-winner HTML templates, custom_data (JSON-parsed).
+  - `name` (string) — name of the jackpot
+  - `description` (string) — description/rules of the jackpot
+  - `image_url` (string) — image url of the jackpot
+  - `winner_template` (JackpotHtmlTemplate) — HTML template for the winner of the jackpt
+    - `id` (string)
+    - `content` (string)
+  - `not_winner_template` (JackpotHtmlTemplate) — HTML template for the not winner of the jackpot
+    - `id` (string)
+    - `content` (string)
+  - `placeholder1` (string) — custom value of placeholder1 defined by operator and can be used in the HTML templates
+  - `placeholder2` (string) — custom value of placeholder2 defined by operator and can be used in the HTML templates
+  - `custom_data` (string) — Custom data as string or JSON string that can be used in API to build custom UI You can request from Smartico to define fields for your specific case that will be managed from Smartico BackOffice Read more here - <https://help.smartico.ai/welcome/products/general-concepts/custom-fields-attributes>
+- `jp_currency` (string) — Native jackpot currency (ISO 4217). Used for winner-history amounts.
+- `user_currency` (string) — Current user's wallet currency. Used to display the pot via `pot.current_pot_amount_user_currency`.
+- `contribution_type` (JackpotContributionType) — Whether the contribution is a fixed amount or a percentage of the bet; see `JackpotContributionType`.
+- `contribution_value` (number) — Amount of contribution per qualifying bet — fixed value or percentage depending on `contribution_type`.
+- `pot` (JackpotPot) — Live pot snapshot (amount, temperature, last explosion timestamp).
+  - `jp_template_id` (number) — Template ID this pot belongs to.
+  - `jp_pot_id` (number) — Stable numeric ID of the current pot instance (rotates when the pot explodes).
+  - `current_pot_amount` (number) — Current pot amount in the jackpot's native currency (`jp_currency`).
+  - `current_pot_amount_user_currency` (number) — Current pot amount converted to the user's wallet currency (`user_currency`).
+  - `explode_date_ts` (number) — Unix ms timestamp of when this pot last exploded; `0` if it has never exploded.
+  - `current_pot_temperature` (JackPotTemparature) — Heat band of the pot relative to its explosion range; see `JackPotTemparature`.
+- `is_opted_in` (boolean) — `true` when the current user is currently opted in.
+- `ach_related_game_allow_all` (boolean) — `true` when every game in the operator catalog contributes; if `true`, skip `getJackpotEligibleGames`.
+- `registration_count` (number) — Number of users currently opted in; always `1` for `JackpotType.Personal`.
+- `expose_winners_over_api` (boolean) — Operator flag: whether the winners list should be displayed. Enforced client-side only — gate `getJackpotWinners` calls on this.
+
+## Behavioral contract
+**Preconditions**
+- No prerequisite calls.
+- Visitor mode supported via `_smartico.vapi(lang).jackpotGet(...)`.
+
+**Server-side eligibility filtering**
+Jackpots are filtered server-side by the user's segments before being
+returned. Templates the user is ineligible for never appear in this
+response — there is no "locked" state to render. An empty result for a
+known-good user typically means none of the configured templates match
+the user's segments / level / brand.
+
+**Filter behavior**
+Passing `related_game_id` returns only jackpots linked to that game (from
+the operator's games catalog). Passing `jp_template_id` returns just that
+single template. With no filter, all active templates the user is
+eligible for are returned. Changing the filter between calls flushes both
+the template cache and the pot cache.
+
+**Two-tier cache**
+- Template definitions: 30 s cache. Re-fetched on filter change or when
+ opt-in / opt-out / a jackpot-win push lands.
+- Pot values: 1 s cache. Re-fetched on every call past the 1-second
+ window so a 1 Hz poll renders a smoothly counting pot.
+
+**`jp_public_meta.custom_data`**
+Server returns this as a JSON-encoded string; the SDK parses it inline so
+consumers always receive either a parsed object or the raw string.
+
+**Personal vs MultiUser jackpots** (see `JackpotType`)
+- `MultiUser` (1) — shared pot; `registration_count` reflects real opted-in
+ user count; temperature transitions fire push events.
+- `Personal` (2) — independent per-user pot; `registration_count` is
+ always 1; temperature push events are suppressed.
+
+**Refresh**
+- `jp_status_id`, segment changes, and operator template edits surface
+ after the 30 s template cache TTL.
+- Opt-in / opt-out / jackpot-win push events all clear the template and
+ pot caches — the next call re-fetches.
+
+**Visitor mode**: supported.
+
+**UI guidance**: see [UI Guide — `jackpotGet`](../../docs/ui/jackpots/UIGuide_jackpotGet.md).
+
+## Example
+```ts
+// Poll every second for live pot counter
+setInterval(async () => {
+    const jackpots = await window._smartico.api.jackpotGet();
+    for (const jp of jackpots) {
+        console.log('[smartico] update pot widget for', jp.jp_public_meta.name, '— amount:', jp.pot.current_pot_amount_user_currency, jp.user_currency, '— temperature:', jp.pot.current_pot_temperature);
+    }
+}, 1000);
+
+// Filtered fetch for a specific game tile
+const linked = await window._smartico.api.jackpotGet({ related_game_id: 'gold-slot2' });
+console.log('[smartico] linked jackpots for game:', linked.length);
+```
+
+### 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
+[
+  {
+    "jp_template_id": 6,
+    "jp_type_id": 1,
+    "jp_public_meta": {
+      "image_url": "https://cdn.example/f8b68a18473c437e32a860-Jackpot1.jpg",
+      "placeholder1": null,
+      "placeholder2": null,
+      "name": "Minor",
+      "description": "1% on top of your bet amount will be contributed to the Jackpot",
+      "not_winner_template": {
+        "id": "0",
+        "content": ""
+      },
+      "priority": "1",
+      "winner_template": {
+        "id": "0",
+        "content": ""
+      },
+      "custom_data": {}
+    },
+    "jp_currency": "EUR",
+    "user_currency": "EUR",
+    "related_games": [],
+    "contribution_type": 2,
+    "contribution_value": 0.2,
+    "pot": {
+      "jp_template_id": 6,
+      "jp_pot_id": 306140,
+      "user_id": null,
+      "current_pot_amount": 12.28367028,
+      "current_pot_amount_user_currency": 12.28367028,
+      "explode_date_ts": null,
+      "current_pot_temperature": 2
+    },
+    "is_opted_in": false,
+    "is_auto_opt_in": true,
+    "ach_related_game_allow_all": true,
+    "registration_count": 17262,
+    "contribution_rules": [
+      {
+        "ruleId": 1,
+        "jpTemplateId": 6,
+        "type": 2,
+        "extEntityIds": [
+          "1111"
+        ],
+        "contributionValue": 4
+      }
+    ],
+    "expose_winners_over_api": false
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `JackpotType`
+- `JackpotDetails`

package/docs/capabilities/jackpotOptIn.md

@@ -0,0 +1,94 @@
+# jackpotOptIn — API (JackpotsOptinResponse)
+
+> Opts the authenticated user into a jackpot.
+> Import: `import { JackpotsOptinResponse } from '@smartico/public-api'`
+> Search terms: jackpotOptIn, jackpots, JackpotsOptinResponse, errCode, errMsg, cid, ts, uuid, payload, duration
+
+## Signature
+```ts
+_smartico.api.jackpotOptIn(filter: { jp_template_id: number }): Promise<JackpotsOptinResponse>
+```
+
+## Parameters
+- `filter.jp_template_id` — ID of the jackpot template to join.
+
+## Returns — `Promise<JackpotsOptinResponse>`
+`JackpotsOptinResponse`:
+- `cid` (number)
+- `ts` (number)
+- `uuid` (string)
+- `errCode` (number)
+- `errMsg` (string)
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode not supported.
+- `jp_template_id` is mandatory — the SDK throws synchronously if missing.
+- The jackpot must currently be active and the user must be in its
+ eligibility segment. Ineligible jackpots are filtered out of
+ `jackpotGet` entirely, so a card the user sees is opt-in-able.
+
+**Error handling**
+The server returns a non-zero `errCode` with a human-readable `errMsg`
+for any failure. Common causes:
+- User is in a control group.
+- Jackpot template is not active (status changed since the user opened
+ the card).
+- User is already opted in (the SDK has no client-side guard against a
+ double-tap; the server enforces).
+- DB race / generic server error.
+
+The SDK does NOT enumerate distinct numeric codes for each cause — branch
+on `errCode === 0` for success and surface `errMsg` as-is for failures.
+
+**Idempotency / re-opt-in semantics**
+- **Already opted in** → returns non-zero `errCode` ("User already opted in").
+- **Previously opted in then opted out** → succeeds silently; the server
+ re-activates the registration. This is not an error path — a user can
+ freely cycle opt-in / opt-out.
+
+**Refresh after success**
+- The SDK clears the template, pot, and winners caches.
+- The next `jackpotGet` call returns `is_opted_in: true` for this
+ template.
+
+**Side effects**
+Fires a `JACKPOT_OPT_IN` engagement event (visible to operator-side
+automation rules). Does NOT immediately move points / gems — contributions
+happen per-bet via the user's gameplay, not on opt-in.
+
+**Visitor mode**: not supported.
+
+**UI guidance**: see [UI Guide — `jackpotOptIn`](../../docs/ui/jackpots/UIGuide_jackpotOptIn.md).
+
+## Example
+```ts
+const r = await window._smartico.api.jackpotOptIn({ jp_template_id: 42 });
+
+if (r.errCode === 0) {
+    console.log('[smartico] opted in — refresh jackpot card to show opt-out CTA');
+} else {
+    console.error('[smartico] opt-in failed — show this message in an error toast:', r.errMsg);
+}
+```
+
+### 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
+{
+  "errCode": 1,
+  "errMsg": "JP User already opted in to Jackpot",
+  "cid": 805,
+  "ts": 1782287009179,
+  "uuid": "00000000-0000-0000-0000-000000000000",
+  "payload": null,
+  "duration": null
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `jackpotGet`
+- `JackpotsOptinResponse`

package/docs/capabilities/jackpotOptOut.md

@@ -0,0 +1,92 @@
+# jackpotOptOut — API (JackpotsOptoutResponse)
+
+> Opts the authenticated user out of a jackpot.
+> Import: `import { JackpotsOptoutResponse } from '@smartico/public-api'`
+> Search terms: jackpotOptOut, jackpots, JackpotsOptoutResponse, errCode, errMsg, cid, ts, uuid, payload, duration
+
+## Signature
+```ts
+_smartico.api.jackpotOptOut(filter: { jp_template_id: number }): Promise<JackpotsOptoutResponse>
+```
+
+## Parameters
+- `filter.jp_template_id` — ID of the jackpot template to leave.
+
+## Returns — `Promise<JackpotsOptoutResponse>`
+`JackpotsOptoutResponse`:
+- `cid` (number)
+- `ts` (number)
+- `uuid` (string)
+- `errCode` (number)
+- `errMsg` (string)
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode not supported.
+- `jp_template_id` is mandatory — the SDK throws synchronously if missing.
+
+**Error handling**
+The server returns a non-zero `errCode` with a human-readable `errMsg` for
+any failure. Common causes:
+- User has never opted in OR is already opted out — server returns
+ non-zero `errCode` for the "already opted out" case. Calling opt-out
+ on a jackpot the user has never registered for typically returns
+ success (the server finds no registration row to update).
+- DB race / generic server error.
+
+Unlike `jackpotOptIn`, opt-out does NOT check the template's status
+— the user can opt out of a jackpot that has been deactivated by the
+operator.
+
+**Idempotency**
+- First opt-out → success.
+- Second opt-out → non-zero `errCode` ("Already opted out").
+- Opt-out of a never-joined jackpot → typically succeeds silently
+ (no registration row to act on).
+
+**Refresh after success**
+- The SDK clears the template, pot, and winners caches.
+- The next `jackpotGet` call returns `is_opted_in: false` for this
+ template and a decremented `registration_count`.
+
+**Side effects**
+Fires a `JACKPOT_OPT_OUT` engagement event for operator-side automation
+rules. The user's existing contributions to the current pot remain in
+place — opt-out stops future contributions but does not refund past ones.
+
+**Visitor mode**: not supported.
+
+**UI guidance**: see [UI Guide — `jackpotOptOut`](../../docs/ui/jackpots/UIGuide_jackpotOptOut.md).
+
+## Example
+```ts
+const r = await window._smartico.api.jackpotOptOut({ jp_template_id: 42 });
+
+if (r.errCode === 0) {
+    console.log('[smartico] opted out — refresh jackpot card to show join CTA');
+} else {
+    console.error('[smartico] opt-out failed — show this message in an error toast:', r.errMsg);
+}
+```
+
+### 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
+{
+  "errCode": 0,
+  "errMsg": "",
+  "cid": 807,
+  "ts": 1782229816688,
+  "uuid": "00000000-0000-0000-0000-000000000000",
+  "payload": null,
+  "duration": null
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `jackpotOptIn`
+- `jackpotGet`
+- `JackpotsOptoutResponse`