@smartico/public-api 0.0.403 → 0.0.405

package/docs/capabilities/playMiniGame.md

@@ -0,0 +1,217 @@
+# playMiniGame — API (TMiniGamePlayResult)
+
+> Plays one round of a mini-game template — runs the server's randomised prize selection, deducts the buy-in cost (if any), credits the won prize, and returns the won `prize_id`.
+> Import: `import { TMiniGamePlayResult } from '@smartico/public-api'`
+> Search terms: playMiniGame, minigames, doSAWSpin, SAWSpin, spin, TMiniGamePlayResult, SAWSpinErrorCode, onUpdate, subscription, err_code, err_message, prize_id, request_id
+
+## Signature
+```ts
+_smartico.api.playMiniGame(template_id: number, { onUpdate, acknowledge = true }: { onUpdate?: (data: TMiniGameTemplate[]) => void, acknowledge?: boolean } = {}): Promise<TMiniGamePlayResult>
+```
+
+## Parameters
+- `template_id` — The mini-game template ID (from `TMiniGameTemplate.id`).
+- `params` — Optional options bag.
+- `params.onUpdate` — Pass a callback to subscribe to subsequent template refreshes (same channel as `getMiniGames`).
+- `params.acknowledge` — Whether the SDK automatically sends and awaits the win acknowledge after the spin. Defaults to `true` (recommended). Set `false` to finalise the win yourself via `miniGameWinAcknowledgeRequest`— see "Acknowledge" above for the request-id caveat.
+
+## Returns — `Promise<TMiniGamePlayResult>`
+`TMiniGamePlayResult`:
+- `err_code` (SAWSpinErrorCode) — Error code. `0` = success (`SAWSpinErrorCode.SAW_OK`). See `playMiniGame` TSDoc for the full table.
+- `err_message` (string) — Optional server-side error message. Present only on non-zero `err_code`; may be empty even then.
+- `prize_id` (number) — ID of the won prize. Look up in `template.prizes` to interpret (including `prize_type === 'no-prize'` for a configured loss slot). Always populated, even when `err_code !== 0`.
+- `request_id` (string) — Correlation id of this spin. Pass it to `miniGameWinAcknowledgeRequest` to finalise the win when playing with `acknowledge: false` — no need to look it up via `getMiniGamesHistory`.
+
+## Behavioral contract
+**Preconditions**
+Read the candidate template from `getMiniGames` and check:
+- `spin_count > 0` for spin-based templates
+ (`saw_buyin_type === 'spins'`).
+- Sufficient balance for paid templates — points / gems /
+ diamonds from `getUserProfile` against
+ `buyin_cost_points` / `_gems` / `_diamonds`.
+- `next_available_spin_ts` is in the past (or unset) — the
+ server enforces a per-period max-attempts cap.
+- Template is currently in its active period
+ (operator-configured `activeFromDate` / `activeTillDate`).
+
+
+
+**Prize handling**
+On `err_code === 0`, `prize_id` matches an entry in
+`template.prizes`. Look up the prize's `prize_type`
+(`MiniGamePrizeTypeName`) to decide UI treatment:
+- `'no-prize'` — the user spun but won nothing (an operator-
+ configured "loss" slot). Buy-in is still deducted.
+- `'points'` / `'gems-and-diamonds'` / `'spin'` — value
+ credited to the user's profile / spin balance; visible on
+ the next refresh.
+- `'bonus'` — surfaces via `getBonuses`.
+- `'jackpot'` — drains the template's `jackpot_current` to the
+ user; resets the accumulator.
+- `'raffle-ticket'` — adds tickets to the relevant raffle.
+- `'mission'` / `'change-level'` — visible via the
+ corresponding domain methods.
+- `'manual'` — operator delivers offline.
+
+**Acknowledge** (the `acknowledge` parameter, default `true`)
+Every spin is finalised by a follow-up acknowledge step that
+marks the win delivered. By default the SDK sends that
+acknowledge and AWAITS it, so `playMiniGame` resolves only after
+the win is finalised server-side. Keep the default unless you
+have a specific reason not to.
+
+Pass `acknowledge: false` to skip that automatic step.
+`playMiniGame` then resolves as soon as the spin result is known,
+without waiting for the win to be marked delivered. You finalise
+it later by calling `miniGameWinAcknowledgeRequest` with the
+`request_id` returned on this result.
+
+What `acknowledge: false` does and does NOT defer:
+- For STANDARD prizes the value is credited at spin time
+ regardless, so opting out does NOT delay the balance change —
+ it only defers the "delivered" bookkeeping and the `is_claimed`
+ flag flipping in `getMiniGamesHistory`.
+- For operator-configured "explicit claim" prizes the credit IS
+ deferred until the spin is acknowledged, so those require an
+ explicit acknowledge to finalise.
+
+A server-side fallback auto-acknowledges ordinary un-acknowledged
+spins after a short delay (about 1–3 minutes), so an ordinary
+prize is never lost even without consumer action. "Explicit
+claim" prizes are excluded from that fallback — if you use
+`acknowledge: false` for one, you MUST acknowledge it explicitly
+or its prize is never credited.
+
+**Idempotency**: NOT idempotent. A double-click sends two
+spins and deducts the buy-in twice. The SDK does NOT guard
+against rapid clicks at the public API level — guard the call
+site with an in-flight flag. The server enforces a per-user
+per-template lock that serialises concurrent requests, so two
+simultaneous calls won't be processed in parallel, but they
+will both be processed sequentially (i.e. both deduct).
+
+**Refresh after success (and after failure)**
+The SDK automatically refreshes the templates cache on every
+spin response and fires any `onUpdate` callback registered via
+`getMiniGames` or this method. After `err_code === 0`, the
+affected template's `spin_count` / `jackpot_current` /
+`next_available_spin_ts` reflect the new state on the
+refreshed array.
+
+**Side effects** (on `err_code === 0`)
+- Buy-in deducted at spin time (points / gems / diamonds / spin
+ tickets — depending on `saw_buyin_type`), already applied by the
+ time the call resolves. Balance updates flow via the
+ user-properties channel (observe via `getUserProfile`).
+- Prize value credited per the prize's type (see "Prize handling"
+ above). Standard prizes are credited at spin time; "explicit
+ claim" prizes are credited when the spin is acknowledged.
+- The play is recorded server-side for analytics / reporting.
+
+**UI guidance**: see [UI Guide — `playMiniGame`](../../docs/ui/minigames/UIGuide_playMiniGame.md).
+
+**Visitor mode**: not supported. Visitor sessions trying to
+spin receive `SAW_VISITOR_STOP_SPIN_REQUEST (-40001)`.
+
+## Example
+```ts
+const games = await window._smartico.api.getMiniGames({
+  onUpdate: (refreshed) => console.log('[smartico] templates refreshed — re-render lobby', refreshed),
+});
+const game = games.find(g => g.id === templateId);
+
+if (!game) {
+  console.log('[smartico] template not in current list — refresh getMiniGames');
+  return;
+}
+if (game.saw_buyin_type === 'spins' && (game.spin_count ?? 0) === 0) {
+  console.log('[smartico] no spins available — disable Play button, show "No spins" message');
+  return;
+}
+
+console.log('[smartico] play starting — set in-flight flag, start game animation (wheel spin / scratch / lootbox open / etc.)');
+const r = await window._smartico.api.playMiniGame(game.id);
+console.log('[smartico] play response received');
+
+if (r.err_code === 0) {
+  const prize = game.prizes.find(p => p.id === r.prize_id);
+  if (prize?.prize_type === 'no-prize') {
+    console.log('[smartico] user lost — animate to the no-prize slot and show "Better luck next time" modal');
+  } else {
+    console.log('[smartico] user won — animate to prize', prize?.name,
+      '— show acknowledge modal per template.acknowledge_type;',
+      'getMiniGames onUpdate fires shortly with refreshed spin_count / jackpot');
+  }
+} else if (r.err_code === 40004) {
+  console.error('[smartico] max spins reached — show countdown to next available spin (use playMiniGameBatch for first_spin_in_period if needed)');
+} else if (r.err_code === -40001) {
+  console.log('[smartico] visitor stopped — silently end the game, no prize modal');
+} else {
+  console.error('[smartico] play failed — show generic error with this message:', r.err_message);
+}
+```
+
+Manual finalisation (`acknowledge: false`) — e.g. an explicit
+"Claim" CTA, or finalising on your own schedule:
+```ts
+const r = await window._smartico.api.playMiniGame(game.id, { acknowledge: false });
+if (r.err_code === 0) {
+  // Spin resolved but not yet acknowledged. For standard prizes the
+  // balance already changed server-side; "explicit claim" prizes
+  // are credited only by the acknowledge below.
+  console.log('[smartico] prize won — show the result / Claim CTA, then finalise');
+
+  // On the user's Claim click, finalise with the request_id from the result.
+  await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
+  console.log('[smartico] win finalised — refresh getUserProfile / getMiniGames to reflect it');
+}
+```
+
+### 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": "",
+  "prize_id": 37373,
+  "request_id": "00000000-0000-0000-0000-000000000000"
+}
+```
+
+## Errors
+**Error codes** (in `err_code`, typed as `SAWSpinErrorCode`)
+- `0` (`SAW_OK`) — success; `prize_id` identifies the won prize
+ in `template.prizes`.
+- `40001` (`SAW_NO_SPINS`) — user has no spin attempts for a
+ spin-based template.
+- `40002` (`SAW_PRIZE_POOL_EMPTY`) — all prize slots in the
+ template are depleted.
+- `40003` (`SAW_NOT_ENOUGH_POINTS`) — insufficient points for a
+ points-cost template.
+- `40004` (`SAW_FAILED_MAX_SPINS_REACHED`) — per-period
+ max-attempts cap reached. The server's
+ `first_spin_in_period` value (exposed in
+ `TMiniGamePlayBatchResult`; not surfaced in the single
+ `TMiniGamePlayResult`) marks the period start.
+- `40007` (`SAW_TEMPLATE_NOT_ACTIVE`) — template outside its
+ active time window.
+- `40009` (`SAW_NOT_IN_SEGMENT`) — user fails the template's
+ visibility segment check, OR (for lootbox variants) the day's
+ prize pool is empty.
+- `40011` (`SAW_NO_BALANCE_GEMS`) — insufficient gems.
+- `40012` (`SAW_NO_BALANCE_DIAMONDS`) — insufficient diamonds.
+- `-40001` (`SAW_VISITOR_STOP_SPIN_REQUEST`) — visitor session
+ tried to play a non-visitor-mode template. The default UI
+ silently stops the game; no prize awarded.
+- other non-zero — generic server error. Surface `err_message`.
+
+## Related
+- `getMiniGames`
+- `getUserProfile`
+- `SAWSpinErrorCode`
+- `TMiniGamePlayBatchResult`
+- `MiniGamePrizeTypeName`
+- `getBonuses`
+- `miniGameWinAcknowledgeRequest`
+- `getMiniGamesHistory`

package/docs/capabilities/playMiniGameBatch.md

@@ -0,0 +1,129 @@
+# playMiniGameBatch — API (TMiniGamePlayBatchResult)
+
+> Plays a mini-game template `spin_count` times in one round-trip.
+> Import: `import { TMiniGamePlayBatchResult } from '@smartico/public-api'`
+> Search terms: playMiniGameBatch, minigames, doSAWSpinBatch, TMiniGamePlayBatchResult, SAWSpinErrorCode, onUpdate, subscription, errCode, errMessage, saw_prize_id, jackpot_amount, first_spin_in_period
+
+## Signature
+```ts
+_smartico.api.playMiniGameBatch(template_id: number, spin_count: number, { onUpdate }: { onUpdate?: (data: TMiniGameTemplate[]) => void } = {}): Promise<TMiniGamePlayBatchResult[]>
+```
+
+## Parameters
+- `template_id` — The mini-game template ID.
+- `spin_count` — Number of spins to play. The server attempts all `spin_count` spins — partial successes are normal when the user runs out of balance / spins mid-batch.
+- `params` — Optional. Pass an `onUpdate` callback to subscribe to subsequent template refreshes.
+
+## Returns — `Promise<TMiniGamePlayBatchResult[]>`
+Array of `TMiniGamePlayBatchResult`. Each item:
+- `saw_prize_id` (number) — ID of the won prize for this spin. Look up in `template.prizes`.
+- `errCode` (SAWSpinErrorCode) — Error code. `0` = success. See `playMiniGameBatch` TSDoc for the full table.
+- `errMessage` (string) — Optional server-side error message.
+- `jackpot_amount` (number) — Jackpot amount the user won, populated when the prize type is `'jackpot'`.
+- `first_spin_in_period` (number) — Epoch ms of the user's first spin in the current cooldown period; populated when `errCode === SAWSpinErrorCode.SAW_FAILED_MAX_SPINS_REACHED`.
+
+## Behavioral contract
+**Result shape note** — `TMiniGamePlayBatchResult` uses
+`errCode` / `errMessage` (camelCase) — DIFFERENT from
+`TMiniGamePlayResult` which uses `err_code` / `err_message`
+(snake_case). Branch on the camelCase keys when reading batch
+results.
+
+**Per-spin independence**
+The server iterates the requested spins and calls the prize
+engine once per entry. If spin #2 fails with `SAW_NO_SPINS`,
+spin #3 is still attempted — the server does NOT stop on first
+error and does NOT roll back successful spins. Each
+`results[i].errCode` is independent.
+
+Practical implication: if the user has 3 spins available and
+requests 5, expect results 0-2 with `errCode === 0` and results
+3-4 with `errCode === SAW_NO_SPINS`.
+
+
+
+**Auto-acknowledge**
+The SDK fires a batch-acknowledge for all `request_id`s after
+the batch response lands — fire-and-forget. Same recovery
+semantics as `playMiniGame`: lost acknowledgements
+become recoverable via `miniGameWinAcknowledgeRequest`
+per row, and a server-side fallback job auto-acknowledges
+stale spins every ~60 seconds.
+
+**Idempotency**: NOT idempotent. A double-click sends two
+batches. Guard the call site with an in-flight flag.
+
+**Refresh after success (and after failure)**
+Same as `playMiniGame` — the templates cache refreshes
+and any `onUpdate` callback registered via `getMiniGames`
+fires with the updated `spin_count` / `jackpot_current`.
+
+**Side effects** (per-spin, on `errCode === 0`)
+Same as `playMiniGame` — buy-in deducted, prize value
+credited per prize type.
+
+**UI guidance**: see [UI Guide — `playMiniGameBatch`](../../docs/ui/minigames/UIGuide_playMiniGameBatch.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const game = (await window._smartico.api.getMiniGames()).find(g => g.id === templateId);
+if (!game) return;
+
+console.log('[smartico] batch play starting — set in-flight flag, animate the chosen N spins sequentially in UI');
+const results = await window._smartico.api.playMiniGameBatch(game.id, 5);
+console.log('[smartico] batch response received — clear in-flight flag');
+
+for (const [i, r] of results.entries()) {
+  if (r.errCode === 0) {
+    const prize = game.prizes.find(p => p.id === r.saw_prize_id);
+    console.log('[smartico] spin', i, 'won:', prize?.name,
+      r.jackpot_amount ? '(jackpot: ' + r.jackpot_amount + ')' : '');
+  } else if (r.errCode === 40004) {
+    const msTillNext = game.max_spins_period_ms! - (Date.now() - (r.first_spin_in_period ?? 0));
+    console.log('[smartico] spin', i, 'capped — ' + Math.ceil(msTillNext / 1000) + ' s until next allowed');
+  } else {
+    console.error('[smartico] spin', i, 'failed —', r.errCode, r.errMessage);
+  }
+}
+```
+
+### 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": 40004,
+    "errMessage": "Failed to spin. Max spins reached",
+    "saw_prize_id": null,
+    "jackpot_amount": null,
+    "first_spin_in_period": 1782287011000
+  }
+]
+```
+
+## Errors
+**Error codes**
+Per-result `errCode` is from `SAWSpinErrorCode`. See
+`playMiniGame` for the full table; the same codes apply
+per spin.
+
+**`first_spin_in_period` field**
+Populated on results where `errCode === SAW_FAILED_MAX_SPINS_REACHED`
+(40004). The value is the epoch-ms timestamp of the user's
+first spin in the current cooldown period. Compute the
+countdown as:
+`template.max_spins_period_ms - (Date.now() - first_spin_in_period)`.
+
+**`jackpot_amount` field**
+Populated on results where the won prize is a jackpot
+(`prize_type === 'jackpot'`). The amount the user just claimed
+from the template's jackpot accumulator.
+
+## Related
+- `playMiniGame`
+- `TMiniGamePlayResult`
+- `SAWSpinErrorCode`
+- `miniGameWinAcknowledgeRequest`
+- `getMiniGames`

package/docs/capabilities/registerInTournament.md

@@ -0,0 +1,187 @@
+# registerInTournament — API (TTournamentRegistrationResult)
+
+> Registers the authenticated user in the specified tournament instance.
+> Import: `import { TTournamentRegistrationResult } from '@smartico/public-api'`
+> Search terms: registerInTournament, tournaments, TTournamentRegistrationResult, TournamentRegistrationError, err_code, err_message
+
+## Signature
+```ts
+_smartico.api.registerInTournament(tournamentInstanceId: number): Promise<TTournamentRegistrationResult>
+```
+
+## Parameters
+- `tournamentInstanceId` — The `instance_id` from `TTournament` (NOT the template `tournament_id`).
+
+## Returns — `Promise<TTournamentRegistrationResult>`
+`TTournamentRegistrationResult`:
+- `err_code` (TournamentRegistrationError) — Error code. `0` = success. See `registerInTournament` TSDoc for the full table.
+- `err_message` (string) — Optional error message; populated on non-zero `err_code`.
+
+## Behavioral contract
+**Preconditions**
+Read the candidate from `getTournamentsList` and gate the call
+on `is_can_register === true`. This composite flag already encodes:
+not already registered, slot available
+(`registration_count < players_max_count`), tournament status is
+REGISTER (or STARTED with late-registration enabled), and the
+registration type is not AUTO. The SDK forwards the call
+unconditionally — calling without satisfying these will return one
+of the error codes below.
+
+For clan tournaments (`is_clan_based === true`), the user must
+already belong to a clan before calling. If they don't, prompt them
+to pick a clan first via `joinClan`, then call
+`registerInTournament` after the clan-join resolves. See "Error
+codes" `1010` below for the server-side safety net.
+
+
+
+**Idempotency**: NOT idempotent. A second call on the same instance
+returns `30004` once the first call has succeeded. The SDK does NOT
+enforce an in-flight lock. The consumer MUST guard the call site
+against double-clicks (set a local "registering" flag on click, clear
+it on response).
+
+**Refresh after success (and after failure)**
+The SDK automatically refreshes the tournament lobby cache on every
+response (success OR error) and fires any `onUpdate` callback
+registered via `getTournamentsList({ onUpdate })`. After
+`err_code === 0`, the affected item's `is_user_registered` /
+`registration_status` / `registration_count` reflect the new
+registered state on the refreshed array. Note that
+`getTournamentInstanceInfo` is NOT auto-refreshed — if the
+detail screen is open, call it again manually.
+
+The user's balance (points / gems / diamonds) is exposed on the
+user-properties channel and updates independently of this call's
+response — subscribe to user-property updates separately if your UI
+shows the balance.
+
+**Side effects** (consumer-observable on success)
+- Balance debited synchronously by the buy-in amount in the
+ tournament's currency (`registration_cost_points`,
+ `registration_cost_gems`, or `registration_cost_diamonds`). For
+ free tournaments no deduction occurs.
+- Server-side analytics events fire downstream
+ (`tournament_user_registered` for immediate-registration types;
+ `tournament_user_registration_pending` or
+ `tournament_registered_pending_qualification` for
+ manual-approval / qualification-based types).
+- Any operator-configured on-join prizes are distributed (e.g.
+ welcome bonus). These surface via the relevant follow-up channels
+ (e.g. `getBonuses`).
+
+**UI guidance**: see [UI Guide — `registerInTournament`](../../docs/ui/tournaments/UIGuide_registerInTournament.md).
+
+**Visitor mode**: not supported. Calling from a visitor session
+returns a generic error, not a typed `TournamentRegistrationError`.
+
+## Example
+```ts
+const tournaments = await window._smartico.api.getTournamentsList({
+  onUpdate: (refreshed) => console.log('[smartico] tournament list updated — re-render lobby from this array', refreshed),
+});
+const tournament = tournaments.find(t => t.instance_id === instanceId);
+
+if (!tournament) {
+  console.log('[smartico] tournament not in current lobby — refresh getTournamentsList and retry');
+  return;
+}
+if (!tournament.is_can_register) {
+  console.log('[smartico] tournament not currently registerable — keep CTA disabled');
+  return;
+}
+
+// Clan tournament + user has no clan → resolve clan first.
+if (tournament.is_clan_based) {
+  const userProfile = window._smartico.api.getUserProfile();
+  const userClanId = userProfile?.clan_id;
+  if (userClanId == null) {
+    console.log('[smartico] clan tournament — open the clan-pick modal first; after joinClan resolves, call registerInTournament again');
+    return;
+  }
+}
+
+console.log('[smartico] registration starting — set in-flight flag, show loading dots on the Join button, keep modal open');
+const r = await window._smartico.api.registerInTournament(tournament.instance_id);
+console.log('[smartico] registration response received — clear in-flight flag');
+
+if (r.err_code === 0 || r.err_code === 30004) {
+  console.log('[smartico] registered (or was already) — close any modal, show a success toast; getTournamentsList onUpdate above will fire with the refreshed array');
+} else if (r.err_code === 1010) {
+  console.log('[smartico] clan required — open the clan-pick modal again (this is the server-side safety net for a clan-leave race)');
+} else if (r.err_code === 30002) {
+  console.error('[smartico] insufficient points — show insufficient-balance UI; deficit:', tournament.registration_cost_points);
+} else if (r.err_code === 300010) {
+  console.error('[smartico] insufficient gems — show insufficient-balance UI; deficit:', tournament.registration_cost_gems);
+} else if (r.err_code === 300011) {
+  console.error('[smartico] insufficient diamonds — show insufficient-balance UI; deficit:', tournament.registration_cost_diamonds);
+} else if (r.err_code === 30005) {
+  console.error('[smartico] segment mismatch — prefer the operator-supplied message:', tournament.segment_dont_match_message || r.err_message);
+} else if (r.err_code === 30008) {
+  console.error('[smartico] tournament full — auto-refresh will hide the button on the refreshed lobby item');
+} else {
+  console.error('[smartico] registration failed — show a generic error toast with this message:', 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`, typed as `TournamentRegistrationError`)
+- `0` — success; the registration is persisted, buy-in deducted,
+ tournament lobby refresh fires.
+- `1010` — `TOURNAMENT_USER_CANNOT_JOIN_WITHOUT_CLAN`: clan-based
+ tournament and the user has no clan. Surface the clan-pick flow
+ (e.g. open a clan-pick modal driven by `getClans` +
+ `joinClan`), then retry registration.
+- `30001` — `TOURNAMENT_INSTANCE_NOT_FOUND`: instance ID is invalid
+ or the tournament was deleted. Refresh the lobby via
+ `getTournamentsList()` and hide the entry from the UI.
+- `30002` — `TOURNAMENT_REGISTRATION_NOT_ENOUGH_POINTS`: insufficient
+ points balance for a points-cost tournament. Show an
+ insufficient-balance UI naming the deficit.
+- `30003` — `TOURNAMENT_INSTANCE_NOT_IN_STATE`: tournament is no
+ longer in a registerable state (finished, cancelled, finalizing,
+ or not yet published with late registration disabled). Refresh
+ the lobby; the button should hide.
+- `30004` — `TOURNAMENT_ALREADY_REGISTERED`: user is already
+ registered. Treat as idempotent success — hide the Register button
+ and refresh the lobby. Usually indicates a stale local state
+ (e.g. registered from another tab).
+- `30005` — `TOURNAMENT_USER_DONT_MATCH_CONDITIONS`: user fails the
+ tournament's segment / entry conditions. Prefer
+ `tournament.segment_dont_match_message` (operator-supplied) over
+ `err_message` when both are available.
+- `30006` — `TOURNAMENT_USER_NOT_REGISTERED`: anomalous on a fresh
+ register call; usually indicates a server-side race. Treat as a
+ generic transient error.
+- `30007` — `TOURNAMENT_CANT_CHANGE_REGISTRATION_STATUS`: status
+ transition not allowed (e.g. re-registering after a finished /
+ cancelled tournament). Show a generic error; do not retry.
+- `30008` — `TOURNAMENT_MAX_REGISTRATIONS_REACHED`: the tournament
+ filled up between the lobby fetch and the registration click.
+ Refresh the lobby — the button will hide on the refreshed item.
+- `300010` — insufficient **gems** balance (gems-cost tournament).
+ Same UI handling as `30002` but for the gems currency.
+- `300011` — insufficient **diamonds** balance (diamonds-cost
+ tournament). Same as `300010` but for diamonds. 
+- other non-zero — generic server error. Surface `err_message` if any.
+
+Note: clan-tournament registration can occasionally surface error
+codes from the clan-join domain (e.g. `1011` — joined-after-start)
+via the same response path. These are members of `JoinClanErrorCode`,
+not `TournamentRegistrationError`. Branch on the numeric value.
+
+## Related
+- `getTournamentsList`
+- `TournamentRegistrationError`
+- `getTournamentInstanceInfo`
+- `getBonuses`

package/docs/capabilities/reportClickEvent.md

@@ -0,0 +1,74 @@
+# reportClickEvent — API
+
+> Records that the user interacted with an engagement — typically tapping a CTA button, following a deep-link, or clicking a popup action.
+> Import: `import { /* types */ } from '@smartico/public-api'`
+> Search terms: reportClickEvent, inbox
+
+## Signature
+```ts
+_smartico.api.reportClickEvent({
+		engagement_uid,
+		activityType,
+		action,
+	}: {
+		/** For inbox: the message's `message_guid` from `getInboxMessages`. */
+		engagement_uid: string;
+		/** `ActivityTypeLimited.Inbox` (`31`) for inbox; `Popup` (`30`) for popups. */
+		activityType: ActivityTypeLimited | number;
+		/** The deep-link / URL the user triggered (optional but recommended for analytics fidelity). */
+		action?: string;
+	}): void
+```
+
+## Parameters
+_None._
+
+## Returns
+_No return value._
+
+## Behavioral contract
+**When to call**
+- Inbox: when the user taps a CTA button on a message or follows
+ a deep-link inside the message body. Pass the deep-link or URL
+ as `action`.
+- Popup: when the user clicks a popup action button.
+
+**Activity types**
+Pass `ActivityTypeLimited.Inbox` (`31`) for inbox,
+`ActivityTypeLimited.Popup` (`30`) for popups.
+
+**`action` payload**
+Pass the deep-link or URL that the user triggered (e.g.
+`'dp:gf_missions'`, `'https://example.com/promo'`). The SDK
+forwards the string to the server for analytics — it does not
+execute the deep-link. To execute deep-links safely, call
+`_smartico.dp(action)` separately.
+
+**Idempotency**: the server records every click event —
+repeated calls add to the count. Fire once per logical user
+action.
+
+**Side effects**: server-side updates the engagement's
+`last_action` field; observable via operator analytics. The SDK
+consumer receives no signal back.
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+// When the user taps a CTA button in an inbox message.
+window._smartico.api.reportClickEvent({
+  engagement_uid: message.message_guid,
+  activityType: 31,  // ActivityTypeLimited.Inbox
+  action: 'dp:gf_missions',
+});
+window._smartico.dp('dp:gf_missions');   // separately execute the deep-link
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `reportImpressionEvent`
+- `ActivityTypeLimited.Inbox`
+- `ActivityTypeLimited.Popup`

package/docs/capabilities/reportImpressionEvent.md

@@ -0,0 +1,67 @@
+# reportImpressionEvent — API
+
+> Records that an engagement (inbox message, popup) was displayed to the user.
+> Import: `import { /* types */ } from '@smartico/public-api'`
+> Search terms: reportImpressionEvent, inbox
+
+## Signature
+```ts
+_smartico.api.reportImpressionEvent({
+		engagement_uid,
+		activityType,
+	}: {
+		/** For inbox: the message's `message_guid` from `getInboxMessages`. For popups: the popup's GUID from the popup display callback. */
+		engagement_uid: string;
+		/** `ActivityTypeLimited.Inbox` (`31`) for inbox; `Popup` (`30`) for popups. */
+		activityType: ActivityTypeLimited | number;
+	}): void
+```
+
+## Parameters
+_None._
+
+## Returns
+_No return value._
+
+## Behavioral contract
+**When to call**
+- Inbox: when a message becomes visible (the user opens / scrolls
+ it into view). The default Smartico UI fires this when the
+ message detail expands, alongside
+ `markInboxMessageAsRead`.
+- Popup: when the popup content is shown to the user.
+
+**Activity types**
+Pass `ActivityTypeLimited.Inbox` (`31`) for inbox messages,
+`ActivityTypeLimited.Popup` (`30`) for popups. Other values
+are not used by the engagement-impression channel.
+
+**Idempotency**: the server records every impression event —
+repeated calls add to the impression count. Don't fire it on
+every re-render; fire it once per logical "display" event
+(modal open, list-row scroll-into-view, popup show).
+
+**Side effects**: server-side increments the engagement's
+`impression_count` and updates `last_impression_date`. The
+counter is observable via operator analytics; the SDK consumer
+receives no signal back.
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+// When the user opens an inbox message in the detail view.
+window._smartico.api.reportImpressionEvent({
+  engagement_uid: message.message_guid,
+  activityType: 31,  // ActivityTypeLimited.Inbox
+});
+console.log('[smartico] inbox impression reported for', message.message_guid, '— no response to await, fire-and-forget');
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `markInboxMessageAsRead`
+- `ActivityTypeLimited.Inbox`
+- `ActivityTypeLimited.Popup`