@smartico/public-api 0.0.379 → 0.0.381

package/dist/WSAPI/WSAPIAvatars.d.ts

@@ -0,0 +1,296 @@
+import { TAvatarDefinition, TAvatarCustomized, TAvatarPrompt, TSetAvatarResult } from './WSAPITypes';
+import { WSAPIMiniGames } from './WSAPIMiniGames';
+/** @group Avatars */
+export declare class WSAPIAvatars extends WSAPIMiniGames {
+    /**
+     * Returns the avatar catalog available to the current user — every pre-defined
+     * avatar configured for the label, with per-user unlock flags (`is_given`, `is_in_use`)
+     * applied server-side.
+     *
+     * The returned `avatar_url` is the absolute CDN URL (the SDK prefixes relative paths
+     * with the configured avatar domain). AI-customized variants are NOT returned here —
+     * those live in {@link getAvatarsCustomized}.
+     *
+     * @remarks
+     * **Preconditions**
+     * - User must be authenticated. Visitor mode is not supported.
+     * - No other prerequisite calls.
+     *
+     * **Visibility filter** (consumer-applied)
+     * Avatars with `hide_until_achieved === true && is_given === false` should be filtered
+     * out of the grid — they represent surprise unlocks that should remain hidden until
+     * the user earns them. The default Smartico UI drops these before rendering.
+     *
+     * **Lock state** (consumer-applied)
+     * Lock condition: `!is_given && avatar_source_type_id !== 0`. Free avatars
+     * (`avatar_source_type_id === 0`) are always selectable; non-free avatars are locked
+     * until `is_given` flips to true (operator grants via campaign, mission reward, store
+     * purchase, etc.).
+     *
+     * **Sort order**
+     * Server does NOT pre-sort. Caller must sort by `priority` ascending (lower = first).
+     *
+     * **Refresh**
+     * - The SDK caches results for 30 seconds.
+     * - {@link setAvatar} clears this cache on completion; the next call re-fetches.
+     * - No push subscription — there is no `onUpdate` callback for avatar methods.
+     * - When `is_given` flips server-side (e.g. the user earns a new avatar), the change
+     *   surfaces only on the next call after the 30-second cache window expires.
+     *
+     * **Visitor mode**: not supported.
+     *
+     * **UI guidance**: see [UI Guide — `getAvatarsList`](../../docs/ui/avatars/UIGuide_getAvatarsList.md).
+     *
+     * @returns Array of {@link TAvatarDefinition} — empty array if the feature is disabled
+     * on the label.
+     *
+     * @example
+     * ```ts
+     * const avatars = await window._smartico.api.getAvatarsList();
+     *
+     * // Apply the standard visibility filter and sort.
+     * const visible = avatars
+     *     .filter((a) => !a.hide_until_achieved || a.is_given)
+     *     .sort((a, b) => a.priority - b.priority);
+     *
+     * console.log('[smartico] visible avatars:', visible.length, '— render as a grid');
+     *
+     * const active = visible.find((a) => a.is_in_use);
+     * if (active) {
+     *     console.log('[smartico] currently in use — overlay a checkmark on this card:', active.avatar_real_id);
+     * }
+     * ```
+     */
+    getAvatarsList(): Promise<TAvatarDefinition[]>;
+    /**
+     * Returns the user's previously generated AI-customized avatar variants.
+     *
+     * Each entry is one AI-generated image derived from a base avatar in the catalog
+     * (the base is identified by `avatar_real_id` and was originally a
+     * {@link TAvatarDefinition} from {@link getAvatarsList}). These variants are stored
+     * server-side under the user record and persist across sessions.
+     *
+     * @remarks
+     * **Preconditions**
+     * - User must be authenticated. Visitor mode is not supported.
+     * - Has meaning only after at least one successful AI customization run (see below).
+     *   New users get an empty array.
+     *
+     * **Where customized avatars come from**
+     * AI customization is **not** a WebSocket method on this SDK. It is a separate HTTP
+     * POST to the operator-configured `avatar-customize` endpoint that takes a base avatar
+     * plus a style prompt from {@link getAvatarPrompts} and returns a generated CDN URL.
+     * Once that POST resolves successfully, the new variant is persisted and surfaces in
+     * the next `getAvatarsCustomized()` call. The variant URL can then be passed to
+     * {@link setAvatar} to activate it.
+     *
+     * **Relation to `getAvatarsList`**
+     * AI variants do NOT appear in {@link getAvatarsList}. Catalog and variants are two
+     * separate collections — combine them client-side if the UI needs a unified view per
+     * base avatar.
+     *
+     * **Sort order**
+     * Server does NOT pre-sort. Caller typically sorts by `dt_created` descending to show
+     * the newest variant first.
+     *
+     * **Refresh**
+     * - The SDK caches results for 30 seconds.
+     * - {@link setAvatar} clears this cache on completion.
+     * - After a successful AI customization POST, the consumer should re-call to surface
+     *   the new variant — the customization endpoint is outside the SDK so the SDK cannot
+     *   auto-invalidate.
+     * - No push subscription.
+     *
+     * **Visitor mode**: not supported.
+     *
+     * **UI guidance**: see [UI Guide — `getAvatarsCustomized`](../../docs/ui/avatars/UIGuide_getAvatarsCustomized.md).
+     *
+     * @returns Array of {@link TAvatarCustomized} — empty if the user has never run AI
+     * customization, or if the feature is disabled on the label.
+     *
+     * @example
+     * ```ts
+     * const variants = await window._smartico.api.getAvatarsCustomized();
+     *
+     * // Group by the base avatar so the UI can show "this base has 3 AI variants".
+     * const byBase = new Map<number, typeof variants>();
+     * for (const v of variants) {
+     *     const list = byBase.get(v.avatar_real_id) ?? [];
+     *     list.push(v);
+     *     byBase.set(v.avatar_real_id, list);
+     * }
+     *
+     * // Newest-first within each base.
+     * for (const list of byBase.values()) {
+     *     list.sort((a, b) => b.dt_created.localeCompare(a.dt_created));
+     * }
+     *
+     * console.log('[smartico] AI variants by base avatar — render as a carousel under each base');
+     * ```
+     */
+    getAvatarsCustomized(): Promise<TAvatarCustomized[]>;
+    /**
+     * Returns the catalog of AI style prompts available for avatar customization.
+     *
+     * Each entry is a "style" the user can apply to a base avatar (e.g. "Cartoon",
+     * "Watercolor", "Cyberpunk"). Prompts carry a cost expressed in points, gems, or
+     * diamonds — applying a prompt deducts the cost server-side as part of the AI
+     * generation request.
+     *
+     * @remarks
+     * **Preconditions**
+     * - User must be authenticated. Visitor mode is not supported.
+     * - No other prerequisite calls. The customization UI typically calls this on demand
+     *   when the user opens the style picker, not on app boot.
+     *
+     * **Cost handling**
+     * Each prompt declares `cost_currency_type_id` (0 = points, 1 = gems, 2 = diamonds)
+     * and `cost_value` (amount). The deduction happens server-side inside the
+     * `avatar-customize` HTTP POST (the AI generation request, which is NOT part of this
+     * SDK). The client should compare `cost_value` against the live balance from
+     * {@link getUserProfile} to disable prompts the user cannot afford, but the server is
+     * the source of truth and will reject under-funded requests authoritatively.
+     *
+     * **Refresh**
+     * - The SDK caches results for 30 seconds.
+     * - Not invalidated by {@link setAvatar} (prompts are catalog metadata, independent
+     *   of the user's active avatar).
+     * - No push subscription.
+     *
+     * **Visitor mode**: not supported.
+     *
+     * **UI guidance**: see [UI Guide — `getAvatarPrompts`](../../docs/ui/avatars/UIGuide_getAvatarPrompts.md).
+     *
+     * @returns Array of {@link TAvatarPrompt} — empty if the AI customization feature is
+     * disabled on the label.
+     *
+     * @example
+     * ```ts
+     * const [prompts, profile] = await Promise.all([
+     *     window._smartico.api.getAvatarPrompts(),
+     *     window._smartico.api.getUserProfile(),
+     * ]);
+     *
+     * for (const p of prompts) {
+     *     // The consumer reads the matching balance from profile based on
+     *     // p.cost_currency_type_id (0=points, 1=gems, 2=diamonds).
+     *     console.log('[smartico] prompt', p.name, '— cost', p.cost_value, 'currency_type', p.cost_currency_type_id);
+     * }
+     * ```
+     */
+    getAvatarPrompts(): Promise<TAvatarPrompt[]>;
+    /**
+     * Activates the specified avatar for the current user. The chosen image becomes the
+     * profile avatar — any subsequent {@link getUserProfile} call will reflect the new
+     * `avatar_url`.
+     *
+     * Pass `avatar_url` (a {@link TAvatarDefinition.url} from the catalog or a
+     * {@link TAvatarCustomized.url} from the AI-variant list) plus `avatar_real_id` of the
+     * base avatar. The server validates ownership before applying — locked avatars are
+     * rejected.
+     *
+     * @remarks
+     * **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 {@link 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`.
+     *
+     * **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).
+     *
+     * **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; {@link 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 {@link 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 ({@link getAvatarPrompts}). Does NOT write a user-visible
+     * entry to {@link getActivityLog}.
+     *
+     * **UI guidance**: see [UI Guide — `setAvatar`](../../docs/ui/avatars/UIGuide_setAvatar.md).
+     *
+     * **Visitor mode**: not supported.
+     *
+     * @param props.avatar_url       Absolute CDN URL of the avatar image. Read from
+     *                                {@link TAvatarDefinition.url} for catalog avatars or
+     *                                {@link TAvatarCustomized.url} for AI variants.
+     * @param props.avatar_real_id   Numeric ID of the base avatar from
+     *                                {@link TAvatarDefinition.avatar_real_id}. For AI
+     *                                variants, this is the `avatar_real_id` of the base
+     *                                they were derived from.
+     * @returns {@link TSetAvatarResult} — check `err_code === 0` for success.
+     *
+     * @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);
+     * }
+     * ```
+     */
+    setAvatar(props: {
+        avatar_url: string;
+        avatar_real_id: number;
+    }): Promise<TSetAvatarResult>;
+}

package/dist/WSAPI/WSAPIBase.d.ts

@@ -0,0 +1,71 @@
+import { SmarticoAPI } from '../SmarticoAPI';
+/** @hidden */
+export declare const CACHE_DATA_SEC = 30;
+/** @hidden */
+export declare const JACKPOT_TEMPLATE_CACHE_SEC = 30;
+/** @hidden */
+export declare const JACKPOT_POT_CACHE_SEC = 1;
+/** @hidden */
+export declare const JACKPOT_WINNERS_CACHE_SEC = 30;
+/** @hidden */
+export declare const JACKPOT_ELIGIBLE_GAMES_CACHE_SEC = 30;
+/** @hidden */
+export declare enum onUpdateContextKey {
+    Saw = "saw",
+    Missions = "missions",
+    TournamentList = "tournamentList",
+    InboxMessages = "inboxMessages",
+    Badges = "badges",
+    Levels = "levels",
+    StoreItems = "storeItems",
+    StoreCategories = "storeCategories",
+    AchCategories = "achCategories",
+    LeaderBoards = "leaderBoards",
+    LevelExtraCounters = "levelExtraCounters",
+    Segments = "segments",
+    StoreHistory = "storeHistory",
+    Jackpots = "jackpots",
+    Pots = "Pots",
+    CustomSections = "customSections",
+    Bonuses = "bonuses",
+    Clans = "clans",
+    SAWHistory = "sawHistory",
+    JackpotWinners = "jackpotWinners",
+    Raffles = "raffles",
+    JackpotEligibleGames = "jackpotEligibleGames",
+    CurrentLevel = "currentLevel",
+    InboxUnreadCount = "inboxUnreadCount",
+    ActivityLog = "activityLog",
+    AvatarsList = "avatarsList",
+    AvatarsCustomized = "avatarsCustomized",
+    AvatarPrompts = "avatarPrompts"
+}
+/**
+ * Abstract base of the SDK's public surface. Holds the shared state
+ * (`api`, `userExtId`, `onUpdateCallback` map) and the generic cache /
+ * subscription helper (`updateEntity`). Domain-specific methods live on
+ * subclasses; the terminator `WSAPI` class composes the whole chain.
+ *
+ * **Consumers should not instantiate this directly** — the SDK constructs
+ * the concrete `WSAPI` via `_smartico.api`.
+ *
+ * @hidden
+ */
+export declare abstract class WSAPIBase {
+    protected api: SmarticoAPI;
+    /** @hidden */
+    protected onUpdateCallback: Map<onUpdateContextKey, (data: any) => void>;
+    /** @hidden */
+    protected userExtId: string;
+    /** @private */
+    constructor(api: SmarticoAPI, userExtId?: string);
+    /** @private */
+    clearCaches(): void;
+    /**
+     * Generic cache-update + subscription-notify helper. Used by domain
+     * classes' `update*` methods to refresh a context and fire any
+     * registered `onUpdate` callback.
+     * @hidden
+     */
+    protected updateEntity(contextKey: onUpdateContextKey, payload: any): Promise<void>;
+}

package/dist/WSAPI/WSAPIBonuses.d.ts

@@ -0,0 +1,240 @@
+import { TBonus, TClaimBonusResult } from './WSAPITypes';
+import { WSAPIMissions } from './WSAPIMissions';
+/** @group Bonuses */
+export declare class WSAPIBonuses extends WSAPIMissions {
+    /**
+     * Returns the bonuses awarded to the current user — both pending
+     * (player-claim required) and already-redeemed. Each bonus carries
+     * a `bonus_status_id` ({@link BonusStatus}) describing its lifecycle
+     * stage and an `is_redeemable` flag that signals whether the
+     * consumer must trigger a manual {@link claimBonus} call.
+     *
+     * Bonuses originate from many sources (CRM rules, mission/tournament
+     * rewards, store redemptions, mini-game prizes, manual operator
+     * awards) and all surface through this single list. The consumer
+     * cannot distinguish the source server-side without operator
+     * coordination.
+     *
+     * @remarks
+     * **Subscription model (`onUpdate`)**
+     * The callback receives the FULL refreshed bonuses list (never a
+     * diff/patch). Each subsequent call to `getBonuses({ onUpdate })`
+     * REPLACES the prior callback. Pass `onUpdate: undefined` (or omit
+     * it) to keep the prior callback in place; the callback is never
+     * auto-cleared.
+     *
+     * **Update triggers** — the callback fires after every
+     * {@link claimBonus} call resolves on this connection (success OR
+     * failure). This is the ONLY trigger.
+     *
+     * Does NOT fire when: a new bonus is awarded server-side
+     * (CRM rule, mission completion, store purchase, etc.), a bonus
+     * expires, or an operator manually issues / cancels a bonus. Those
+     * changes surface only on the next cache miss (after the 30 s TTL).
+     * Re-call `getBonuses()` manually if your UI needs near-live state
+     * for server-driven awards.
+     *
+     * **Reading state from the returned bonus**
+     * Drive UI bucketing from `bonus_status_id` (enum {@link BonusStatus}):
+     *
+     * - `COUPON_ISSUED` (2) — actionable; player must claim. Pair with
+     *   `is_redeemable === true` to gate the Claim button.
+     * - `REDEEM_FAILED` (4) — also actionable; the previous claim
+     *   attempt failed but the bonus is still valid. Surface a retry CTA
+     *   — the default Smartico UI treats this identically to
+     *   `COUPON_ISSUED` from the player's perspective.
+     * - `REDEEMED` (3) — historical; show in a "claimed" tab.
+     * - `New` (1), `COUPON_ISSUE_FAILED` (5), `EXPIRED` (6) — these
+     *   should not normally reach the client and are typically filtered
+     *   out by operator-side widget configuration; if they do appear,
+     *   they have no player-actionable state.
+     *
+     * `is_redeemable` is the authoritative gate for showing the Claim
+     * button — it's `true` only when the bonus is in a claimable status
+     * AND the operator's integration uses a coupon model (where the
+     * player must explicitly trigger delivery). Auto-redeemed bonuses
+     * arrive already in `REDEEMED` state with `is_redeemable: false`.
+     *
+     * **Field hierarchy — display amount**
+     * Bonuses carry both template-level (`label_bonus_template_meta_map.description`)
+     * and instance-level (`bonus_meta_map.uiAmount`) display strings.
+     * Prefer `bonus_meta_map.uiAmount` when present — it's the dynamic
+     * amount computed at issuance time (e.g. from a dynamic-bonus
+     * formula). Fall back to `label_bonus_template_meta_map.description`
+     * (which can include HTML; sanitize before injecting).
+     *
+     * **Date format**
+     * `create_date` and `redeem_date` are ISO 8601 UTC strings WITHOUT
+     * a timezone suffix (`"YYYY-MM-DDTHH:MM:SS"`). Parse as UTC and
+     * display in the user's local timezone. `redeem_date` is absent
+     * until the bonus reaches `REDEEMED` status.
+     *
+     * **Cache TTL**: the SDK caches the response for 30 seconds. Cache
+     * is fully cleared on login / logout.
+     *
+     * **Idempotency / Side effects**: safe. Read-only.
+     *
+     * **UI guidance**: see [UI Guide — `getBonuses`](../../docs/ui/bonuses/UIGuide_getBonuses.md).
+     *
+     * **Visitor mode**: not supported.
+     *
+     * @param params              Optional. Omit to fetch without subscribing.
+     * @param params.onUpdate     Callback invoked with the full refreshed
+     *                            bonuses list after every
+     *                            {@link claimBonus} resolves. Each call
+     *                            to `getBonuses` overwrites the prior
+     *                            callback.
+     * @returns                   Promise resolving to the bonuses list.
+     *                            Empty array if no bonuses are visible.
+     *
+     * @example
+     * ```ts
+     * const bonuses = await window._smartico.api.getBonuses({
+     *   onUpdate: (refreshed) => {
+     *     console.log('[smartico] bonuses refreshed (after claimBonus) — re-render the bonuses UI from this array:', refreshed);
+     *   },
+     * });
+     *
+     * // Bucket into pending vs redeemed tabs. The default Smartico UI groups
+     * // COUPON_ISSUED + REDEEM_FAILED into the same "Pending" tab.
+     * const pending = bonuses.filter(b =>
+     *   b.bonus_status_id === 2 || b.bonus_status_id === 4  // COUPON_ISSUED or REDEEM_FAILED
+     * );
+     * const redeemed = bonuses.filter(b => b.bonus_status_id === 3);  // REDEEMED
+     *
+     * console.log('[smartico] render bonus tabs: pending=', pending.length, 'redeemed=', redeemed.length);
+     *
+     * // Render each pending bonus card; show Claim button only when redeemable.
+     * for (const b of pending) {
+     *   const amount = b.bonus_meta_map?.uiAmount || b.label_bonus_template_meta_map?.description;
+     *   if (b.is_redeemable) {
+     *     console.log('[smartico] render Claim button for bonus', b.bonus_id, '— amount:', amount);
+     *   } else {
+     *     console.log('[smartico] render bonus as informational (no Claim button) — amount:', amount);
+     *   }
+     * }
+     *
+     * // Server-awarded bonuses (e.g. from a CRM campaign) do NOT push;
+     * // poll if you need near-live awareness.
+     * setInterval(async () => {
+     *   const fresh = await window._smartico.api.getBonuses();
+     *   const newCount = fresh.filter(b => b.bonus_status_id === 2 || b.bonus_status_id === 4).length;
+     *   console.log('[smartico] poll tick — pending bonuses now:', newCount);
+     * }, 30_000);
+     * ```
+     */
+    getBonuses({ onUpdate }?: {
+        onUpdate?: (data: TBonus[]) => void;
+    }): Promise<TBonus[]>;
+    /**
+     * Triggers manual redemption of a coupon-model bonus the user has
+     * been awarded. For bonuses with `is_redeemable === true` returned
+     * by {@link getBonuses}, this is the call that asks the operator's
+     * integration to actually credit the bonus to the player's account.
+     * Bonuses on integrations that auto-redeem arrive already in
+     * `REDEEMED` state and do not require this call.
+     *
+     * Use this for `bonus_status_id` of `COUPON_ISSUED` (2) as the
+     * first-time claim, and for `REDEEM_FAILED` (4) as a retry after a
+     * prior unsuccessful attempt.
+     *
+     * @remarks
+     * **Preconditions**
+     * Read the candidate bonus from {@link getBonuses} and gate the
+     * call on `is_redeemable === true`. The SDK forwards the request
+     * unconditionally — calling on a non-claimable bonus returns
+     * `err_code = -1`.
+     *
+     * **Error codes** (in `err_code`)
+     *
+     * The SDK currently types `err_code` as {@link SAWSpinErrorCode} for
+     * historical reasons, but the values returned by this method come
+     * from the server's general error space and are NOT mini-game codes.
+     * Branch on the numeric values:
+     *
+     * - `0` — success; the bonus has been redeemed and the operator's
+     *   integration has credited the player's account.
+     * - `-1` — bonus not claimable: not found, already claimed by
+     *   another session, or its status is no longer `COUPON_ISSUED` /
+     *   `REDEEM_FAILED`. Treat as idempotent — refresh
+     *   {@link getBonuses} and reconcile.
+     * - `1` — generic server error. Transient; allow retry after a brief
+     *   delay.
+     * - `9999` — uncaught server exception. Treat as a transient failure;
+     *   surface a generic error and allow retry.
+     * - other non-zero — generic server error. Surface `err_message` if
+     *   any.
+     *
+     * **`success` field is unreliable**: the wire response does not
+     * carry a `success` boolean — the field on `TClaimBonusResult` will
+     * be `undefined` in practice. Always branch on `err_code === 0`
+     * for the success check.
+     *
+     * **Refresh after success (and after failure)**
+     * The SDK automatically refreshes the bonuses cache on every
+     * response (success OR failure) and fires any `onUpdate` callback
+     * registered via {@link getBonuses}'s `onUpdate`. After
+     * `err_code === 0`, the redeemed bonus shifts from
+     * `COUPON_ISSUED` / `REDEEM_FAILED` to `REDEEMED` on the refreshed
+     * array, with `redeem_date` populated. After a failure, the bonus
+     * typically lands in `REDEEM_FAILED` and remains claimable for a
+     * retry.
+     *
+     * **Idempotency**: NOT idempotent at the SDK level. A second call
+     * returns `err_code = -1` once the first has succeeded — treat that
+     * as success in the UI rather than as a real error. Guard the call
+     * site against double-clicks (set a local "claiming" flag on click,
+     * clear it on response).
+     *
+     * **Side effects** (on `err_code === 0`)
+     * - Bonus status transitions to `REDEEMED`; `redeem_date` is set.
+     * - The operator's integration credits the player's account
+     *   externally. The SDK does not observe that credit directly —
+     *   balance updates flow over the user-properties channel from the
+     *   operator's side, not from this response.
+     * - Server-side analytics events fire downstream (not directly
+     *   observable from the SDK).
+     *
+     * **UI guidance**: see [UI Guide — `claimBonus`](../../docs/ui/bonuses/UIGuide_claimBonus.md).
+     *
+     * **Visitor mode**: not supported.
+     *
+     * @param bonus_id  The `bonus_id` from a `TBonus` returned by
+     *                  {@link getBonuses}.
+     * @returns `{ err_code, err_message, success? }`; success when
+     *          `err_code === 0` (or `err_code === -1` when treated as
+     *          idempotent no-op). The `success` field is unreliable —
+     *          ignore it.
+     *
+     * @example
+     * ```ts
+     * const bonuses = await window._smartico.api.getBonuses({
+     *   onUpdate: (refreshed) => console.log('[smartico] bonuses refreshed — re-render from this array', refreshed),
+     * });
+     * const bonus = bonuses.find(b => b.bonus_id === bonusId);
+     *
+     * if (!bonus) {
+     *   console.log('[smartico] bonus no longer visible — refresh list and hide CTA');
+     *   return;
+     * }
+     * if (!bonus.is_redeemable) {
+     *   console.log('[smartico] bonus is not claimable (auto-redeemed or already finalised) — keep CTA hidden');
+     *   return;
+     * }
+     *
+     * console.log('[smartico] claim starting — set in-flight flag, show loading dots on the Claim button, keep the modal open');
+     * const r = await window._smartico.api.claimBonus(bonus.bonus_id);
+     * console.log('[smartico] claim response received — clear in-flight flag');
+     *
+     * if (r.err_code === 0 || r.err_code === -1) {
+     *   console.log('[smartico] claim succeeded (or was already done) — show a success toast; the getBonuses onUpdate above will fire with the refreshed list');
+     * } else if (r.err_code === 9999) {
+     *   console.error('[smartico] uncaught server exception — show a generic error toast and allow retry');
+     * } else {
+     *   console.error('[smartico] claim failed — surface this error message to the user; the bonus will move to REDEEM_FAILED state and remain claimable for a retry:', r.err_message);
+     * }
+     * ```
+     */
+    claimBonus(bonus_id: number): Promise<TClaimBonusResult>;
+    protected updateBonuses(): Promise<void>;
+}