@smartico/public-api 0.0.380 → 0.0.381

package/src/WSAPI/WSAPIAvatars.ts

@@ -14,19 +14,63 @@ import { WSAPIMiniGames } from './WSAPIMiniGames';
 /** @group Avatars */
 export class WSAPIAvatars extends WSAPIMiniGames {
 	/**
-	 * Returns the list of avatars available in the catalog for the current user.
-	 * The response includes both free avatars and earned/purchased ones.
-	 * Avatars with `hide_until_achieved = true` and `is_given = false` should be hidden from the user.
-	 * The result is cached for 30 seconds.
+	 * 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.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.getAvatarsList().then((result) => {
-	 *      console.log(result);
-	 * });
-	 * ```
+	 * 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**
+	 * **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);
+	 * }
+	 * ```
 	 */
 	public async getAvatarsList(): Promise<TAvatarDefinition[]> {
 		return OCache.use(
@@ -38,18 +82,70 @@ export class WSAPIAvatars extends WSAPIMiniGames {
 	}
 
 	/**
-	 * Returns the list of AI-customized avatars for the current user.
-	 * Each entry represents a previously generated AI customization for a specific base avatar.
-	 * The result is cached for 30 seconds.
+	 * Returns the user's previously generated AI-customized avatar variants.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.getAvatarsCustomized().then((result) => {
-	 *      console.log(result);
-	 * });
-	 * ```
+	 * 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));
+	 * }
 	 *
-	 * **Visitor mode: not supported**
+	 * console.log('[smartico] AI variants by base avatar — render as a carousel under each base');
+	 * ```
 	 */
 	public async getAvatarsCustomized(): Promise<TAvatarCustomized[]> {
 		return OCache.use(
@@ -61,18 +157,53 @@ export class WSAPIAvatars extends WSAPIMiniGames {
 	}
 
 	/**
-	 * Returns the list of AI customization prompts (styles) available for avatar customization.
-	 * Each prompt represents a visual style that can be applied to a base avatar.
-	 * The result is cached for 30 seconds.
+	 * Returns the catalog of AI style prompts available for avatar customization.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.getAvatarPrompts().then((result) => {
-	 *      console.log(result);
-	 * });
-	 * ```
+	 * 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**
+	 * **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);
+	 * }
+	 * ```
 	 */
 	public async getAvatarPrompts(): Promise<TAvatarPrompt[]> {
 		return OCache.use(
@@ -84,27 +215,114 @@ export class WSAPIAvatars extends WSAPIMiniGames {
 	}
 
 	/**
-	 * Sets the specified avatar as the active avatar for the current user.
-	 * Pass `avatar_url` (the `TAvatarDefinition.url` path or a CDN URL for AI-customized avatars)
-	 * and `avatar_real_id` from the avatar catalog.
-	 * After a successful call, the avatar list cache is cleared so the next `getAvatarsList()` call reflects `is_in_use`.
+	 * 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`.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.getAvatarsList().then((avatars) => {
-	 *      const avatar = avatars.find((a) => !a.hide_until_achieved || a.is_given);
-	 *      if (avatar) {
-	 *          _smartico.api.setAvatar({
-	 *              avatar_url: avatar.url,
-	 *              avatar_real_id: avatar.avatar_real_id,
-	 *          }).then((result) => {
-	 *              console.log(result);
-	 *          });
-	 *      }
+	 * 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,
 	 * });
-	 * ```
 	 *
-	 * **Visitor mode: not supported**
+	 * 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);
+	 * }
+	 * ```
 	 */
 	public async setAvatar(props: { avatar_url: string; avatar_real_id: number }): Promise<TSetAvatarResult> {
 		if (!props.avatar_url) {

package/src/WSAPI/WSAPIBonuses.ts

@@ -12,12 +12,125 @@ import { WSAPIMissions } from './WSAPIMissions';
 /** @group Bonuses */
 export class WSAPIBonuses extends WSAPIMissions {
 	/**
-	 * Returns all the bonuses for the current user
-	 * The returned bonuses are cached for 30 seconds. But you can pass the onUpdate callback as a parameter.
-	 * Note that each time you call getBonuses with a new onUpdate callback, the old one will be overwritten by the new one.
-	 * The onUpdate callback will be called on bonus claimed and the updated bonuses will be passed to it.
+	 * 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.
 	 *
-	 * **Visitor mode: not supported**
+	 * 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);
+	 * ```
 	 */
 	public async getBonuses({ onUpdate }: { onUpdate?: (data: TBonus[]) => void } = {}): Promise<TBonus[]> {
 		if (onUpdate) {
@@ -28,12 +141,113 @@ export class WSAPIBonuses extends WSAPIMissions {
 	}
 
 	/**
-	 * Claim the bonus by bonus_id. Returns the err_code in case of success or error.
-	 * Note that this method can be used only on integrations where originally failed bonus can be claimed again.
-	 * For example, user won a bonus in the mini-game, but Operator rejected this bonus.
-	 * This bonus will be available for the user to claim again.
+	 * 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');
 	 *
-	 * **Visitor mode: not supported**
+	 * 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);
+	 * }
+	 * ```
 	 */
 	public async claimBonus(bonus_id: number): Promise<TClaimBonusResult> {
 		const r = await this.api.bonusClaimItem(this.userExtId, bonus_id);