@smartico/public-api 0.0.378 → 0.0.380

package/src/WSAPI/WSAPIStore.ts

@@ -0,0 +1,732 @@
+import { ECacheContext, OCache } from '../OCache';
+import {
+	TBuyStoreItemResult,
+	TStoreCategory,
+	TStoreItem,
+} from './WSAPITypes';
+import {
+	CACHE_DATA_SEC,
+	onUpdateContextKey,
+} from './WSAPIBase';
+import { WSAPIBonuses } from './WSAPIBonuses';
+
+/** @group Store */
+export class WSAPIStore extends WSAPIBonuses {
+	private storeHistoryOnUpdateParams: { limit: number; offset: number } = { limit: 20, offset: 0 };
+
+	private storeHistoryCacheKey(limit: number, offset: number): string {
+		return `${onUpdateContextKey.StoreHistory}:${limit}:${offset}`;
+	}
+
+	/**
+	 * Returns the catalog of buyable store items visible to the current user,
+	 * scoped server-side to what the user is qualified to see. Optionally
+	 * subscribes to live updates via `onUpdate`: the callback is invoked with
+	 * the full refreshed catalog after every purchase the user makes from this
+	 * device.
+	 *
+	 * The returned list is the canonical source of truth for store state
+	 * (`can_buy`, `pool`, `discounted_price`, `active_till_date`, etc.).
+	 * Consumers should NEVER mutate it optimistically — always re-fetch (or
+	 * wait for the `onUpdate` callback) to observe the new state.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * The catalog is per-user. Visitor mode is supported with caveats (see
+	 * "Visitor mode" below). For the authenticated path, the user's balances
+	 * (`ach_points_balance`, `ach_gems_balance`, `ach_diamonds_balance` from
+	 * {@link getUserProfile}) must be tracked client-side to drive the
+	 * affordability state of the Buy button — the SDK does not pre-compute
+	 * affordability into `can_buy`.
+	 *
+	 * **Subscription model (`onUpdate`)**
+	 * The callback receives the FULL refreshed catalog (never a diff/patch).
+	 * Each subsequent call to `getStoreItems({ onUpdate })` REPLACES the prior
+	 * callback — only one active subscriber at a time. Pass
+	 * `onUpdate: undefined` (or omit it) to keep the prior callback in place;
+	 * the callback is never auto-cleared.
+	 *
+	 * **Update triggers**
+	 *
+	 * Fires after: any `buyStoreItem(...)` call resolves on this connection
+	 * (success OR failure). This is the ONLY trigger. The refreshed array
+	 * reflects pool decrement on the just-bought item, per-period purchase
+	 * cap re-evaluation on `can_buy`, and any `purchased_today` /
+	 * `purchased_this_week` / `purchased_this_month` flips visible via
+	 * {@link getStorePurchasedItems}.
+	 *
+	 * Does NOT fire for:
+	 * - Operator-side BO catalog edits (price, ribbons, pool seed, segment
+	 *   conditions, new/removed items) — surface only on the next cache miss.
+	 * - Concurrent purchases by OTHER users — the current user's view of
+	 *   `pool` may be stale until they themselves refresh.
+	 * - User balance changes from gameplay — the catalog is independent of
+	 *   balance; the consumer drives Buy-button affordability from a
+	 *   separately-tracked balance source.
+	 * - Items going past their `active_till_date` while the page is open —
+	 *   the item simply disappears on the next refresh.
+	 *
+	 * **Server-side filtering** (what's already excluded before the SDK sees it)
+	 * - Items outside the `[active_from_date, active_till_date]` window —
+	 *   past the till-date, items are ALWAYS filtered out server-side.
+	 * - Items the user fails visibility-segment / visibility-condition
+	 *   checks for.
+	 * - Items configured to hide-when-empty whose pool has reached 0
+	 *   (per-item operator flag). Items without that flag are still returned
+	 *   with `pool === 0` so a "Sold out" state can be rendered.
+	 * - Items where the per-period bought-count cap is reached (and the
+	 *   operator chose to hide rather than just disable).
+	 *
+	 * **Reading state from the returned item**
+	 * The catalog row carries everything a Buy button needs except the user's
+	 * balance: `can_buy` already reflects segment / visibility / per-period
+	 * cap checks, but the SDK does NOT pre-compute balance affordability —
+	 * compare `discounted_price ?? price` against the user's balance for
+	 * `purchase_type` (`ach_points_balance` / `ach_gems_balance` /
+	 * `ach_diamonds_balance` from {@link getUserProfile}). `purchase_type` is
+	 * per-item (`'points'` / `'gems'` / `'diamonds'`); operators can mix
+	 * currencies within a single catalog. For sold-out display, `pool === 0`
+	 * means the operator chose to keep the item visible — render an "Out of
+	 * stock" overlay. When `discounted_price` is set, render `price` with a
+	 * strikethrough and `discounted_price` as the active price; the
+	 * accompanying `discount_price_ribbon` is either a percentage preset
+	 * (`'10'`, `'15'`, `'20'`, `'25'`, `'50'`) or the literal `'custom'`
+	 * (in which case `custom_ribbon_image` is the artwork at 250×300 px).
+	 * A live countdown for time-limited items is rendered only when the
+	 * operator has enabled the per-item `show_timer` flag.
+	 *
+	 * **Cross-references**
+	 * `category_ids` joins to `TStoreCategory.id` from
+	 * {@link getStoreCategories} (many-to-many — an item can belong to
+	 * multiple categories). Items with `only_in_custom_section: true` are
+	 * returned in the catalog but intended for their custom-section view
+	 * only — filter them client-side for the main store view. The
+	 * history-only fields (`purchase_ts`, `purchase_points_amount`, the
+	 * `purchased_*` booleans) are populated only by
+	 * {@link getStorePurchasedItems}, not by this method.
+	 *
+	 * **Idempotency**: yes. `getStoreItems` is a pure read. Calling it
+	 * repeatedly within the 30-second cache window resolves from the cache
+	 * without a network round-trip.
+	 *
+	 * **Side effects** (of a successful purchase that triggers `onUpdate`)
+	 * Documented here because the consumer's `onUpdate` handler will observe
+	 * the resulting state changes on the next refreshed array:
+	 * - Points / gems / diamonds balance deducted per `purchase_type`. The
+	 *   new balance becomes visible on the user's gamification profile via
+	 *   the SDK's user-properties update channel (`ach_points_balance` /
+	 *   `ach_gems_balance` / `ach_diamonds_balance`).
+	 * - `pool` decremented for limited-stock items.
+	 * - `type = 'bonus'` → a CRM bonus is granted; surfaces via
+	 *   {@link getBonuses}.
+	 * - `type = 'raffleticket'` → raffle tickets granted; surfaces via
+	 *   `getRaffles`.
+	 * - `type = 'changelevel'` → user's level adjusted; surfaces via
+	 *   {@link getCurrentLevel}.
+	 * - `type = 'minigamespin'` → SAW spin attempts granted; visible via the
+	 *   mini-game APIs.
+	 * - `type = 'prizedrop'` → one prize-drop attempt granted.
+	 * - `type = 'tangible'` → no automatic gameplay effect; the purchase is
+	 *   recorded for the operator's manual fulfillment (e.g. physical merch).
+	 *
+	 * **UI guidance**: see [UI Guide — `getStoreItems`](../../docs/ui/store/UIGuide_getStoreItems.md).
+	 *
+	 * @param params              Optional. Omit to fetch without subscribing.
+	 * @param params.onUpdate     Callback invoked with the full refreshed
+	 *                            catalog after every {@link buyStoreItem}
+	 *                            round-trip on this connection. Each call to
+	 *                            `getStoreItems` overwrites the prior
+	 *                            callback. Never fires in visitor mode.
+	 * @returns                   Promise resolving to the catalog of store
+	 *                            items visible to the user. Empty array if
+	 *                            the user has no items (or if the visitor
+	 *                            proxy user has none configured).
+	 *
+	 * @example
+	 * ```ts
+	 * // 1. Initial fetch + subscribe to live updates
+	 * const items = await window._smartico.api.getStoreItems({
+	 *   onUpdate: (refreshed) => {
+	 *     console.log('[smartico] store catalog refreshed after a purchase — re-render the entire store UI from this array, do not merge with prior state:', refreshed);
+	 *
+	 *     // 2. onUpdate fires only after the current user's own purchase
+	 *     //    round-trip. Pool counts and can_buy flags are now current
+	 *     //    for this user.
+	 *     const soldOut = refreshed.filter(i => i.pool === 0);
+	 *     if (soldOut.length > 0) {
+	 *       console.log('[smartico] these items are now sold out — render an "Out of stock" overlay on each:', soldOut.map(i => i.id));
+	 *     }
+	 *   },
+	 * });
+	 *
+	 * // 3. Live affordability per item. Compare each item's price against
+	 * //    the user's balance for its purchase_type (read from
+	 * //    getUserProfile(), kept live by the SDK's user-properties channel).
+	 * const profile = window._smartico.api.getUserProfile();
+	 * const balances = {
+	 *   points: profile?.ach_points_balance ?? 0,
+	 *   gems: profile?.ach_gems_balance ?? 0,
+	 *   diamonds: profile?.ach_diamonds_balance ?? 0,
+	 * };
+	 *
+	 * // 4. Filter out items that are custom-section-only for the main view.
+	 * const mainViewItems = items.filter(i => !i.only_in_custom_section);
+	 *
+	 * // 5. Bucket each item's button state for rendering.
+	 * for (const i of mainViewItems) {
+	 *   const activePrice = i.discounted_price ?? i.price;
+	 *   const canAfford = balances[i.purchase_type] >= activePrice;
+	 *   if (i.pool === 0) {
+	 *     console.log('[smartico] item', i.id, 'is sold out — render disabled Buy with "Out of stock" overlay');
+	 *   } else if (i.can_buy === false) {
+	 *     console.log('[smartico] item', i.id, 'is not eligible — render disabled Buy and surface cant_buy_message on the popup:', i.cant_buy_message);
+	 *   } else if (!canAfford) {
+	 *     console.log('[smartico] item', i.id, 'is unaffordable — render disabled Buy and show "short by" line on popup; deficit =', activePrice - balances[i.purchase_type], i.purchase_type);
+	 *   } else {
+	 *     console.log('[smartico] item', i.id, 'is buyable — render enabled Buy at price', activePrice, i.purchase_type);
+	 *   }
+	 * }
+	 *
+	 * // 6. Visitor-mode equivalent: onUpdate is accepted but never fires.
+	 * //    Re-poll if you need fresh data; buyStoreItem is not supported.
+	 * // const visitorItems = await window._smartico.vapi('EN').getStoreItems();
+	 * // console.log('[smartico] visitor catalog is the brand proxy user\'s — per-user fields are not meaningful');
+	 * ```
+	 */
+	public async getStoreItems({ onUpdate }: { onUpdate?: (data: TStoreItem[]) => void } = {}): Promise<TStoreItem[]> {
+		if (onUpdate) {
+			this.onUpdateCallback.set(onUpdateContextKey.StoreItems, onUpdate);
+		}
+		return OCache.use(
+			onUpdateContextKey.StoreItems,
+			ECacheContext.WSAPI,
+			() => this.api.storeGetItemsT(this.userExtId),
+			CACHE_DATA_SEC,
+		);
+	}
+
+	/**
+	 * Purchase a specific store item on behalf of the current user. Spends
+	 * the user's points / gems / diamonds (depending on the item's
+	 * `purchase_type`) and triggers reward delivery (bonus issuance, mini-game
+	 * spin grant, level change, prize-drop, raffle ticket, or tangible item).
+	 *
+	 * A successful response (`err_code === 0`) means the funds have already
+	 * been debited and the reward has been queued / granted server-side. The
+	 * user's balance change arrives over a separate push channel, not in this
+	 * response — see "Refresh after success" below.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * Read the candidate item from `getStoreItems()` first and gate the call
+	 * on these fields:
+	 * - `can_buy === true` — server-derived; combines segment / visibility
+	 *   conditions and any operator-set restrictions.
+	 * - `pool == null || pool > 0` — `null` means unlimited stock; a positive
+	 *   number means N units remain.
+	 * - User's balance for the item's `purchase_type`
+	 *   (`'points'` / `'gems'` / `'diamonds'`) is `>= price` (or
+	 *   `>= discounted_price` if set). Balances are not on `TStoreItem` —
+	 *   read them from the user properties returned by `getUserState()`.
+	 * - If `active_till_date` is set, it is in the future.
+	 *
+	 * Calling without satisfying these will most likely return a non-zero
+	 * `err_code` (one of the codes below). The SDK does not pre-validate
+	 * — it forwards the request to the server unconditionally.
+	 *
+	 * **Error codes** (in `err_code`)
+	 * - `0` — success; funds debited and reward delivered.
+	 * - `1` — generic server error / control-group rejection. Treat as a
+	 *   transient failure; show a "try again later" message.
+	 * - `106` — label mismatch detected before the purchase transaction
+	 *   (e.g. cross-label item id). From a consumer perspective: the item is
+	 *   not purchasable by this user.
+	 * - `11000` (`SHOP_NO_BALANCE`) — insufficient **points** balance.
+	 *   Show an insufficient-balance message that names how many points are
+	 *   missing (`price - current_points_balance`). The Buy button on the
+	 *   item should already be disabled when this is the case; this code
+	 *   normally fires only on a stale local balance.
+	 * - `11001` (`SHOP_WRONG_LABEL`) — user-vs-item label mismatch detected
+	 *   inside the purchase transaction. Distinct from `106`; both mean
+	 *   "not purchasable by this user" from the consumer's perspective.
+	 *   Surface as a generic "item not available" message.
+	 * - `11002` (`SHOP_FAILED_TO_BUY_BONUS`) — the bonus configured on the
+	 *   store item couldn't be issued (bad / disabled bonus config on the
+	 *   operator side). Funds are NOT debited. Surface a generic error and
+	 *   advise the user to contact support if it persists.
+	 * - `11003` (`SHOP_FAILED_TO_BUY_SHOP_ITEM_CONDITION`) — the item's
+	 *   **visibility** segment condition is not satisfied. Shouldn't be
+	 *   reachable through a correctly-rendered UI (the item shouldn't be
+	 *   shown in the first place); usually indicates a stale local store
+	 *   list. Re-fetch via `getStoreItems()`.
+	 * - `11004` (`SHOP_FAILED_TO_BUY_SHOP_ITEM_CONDITION_PURSHASE`) — the
+	 *   item's **purchase** segment condition is not satisfied (the item is
+	 *   visible but the user is not in the buyable segment). Surface a
+	 *   localized "try again later" / "you're not eligible" message; do not
+	 *   retry automatically.
+	 * - `11005` (`SHOP_FAILED_TO_BUY_MATCHING_BONUS`) — matching-bonus
+	 *   coupon issuance failed (variant of `11002` for matching-deposit
+	 *   bonuses). Funds are NOT debited. Surface a generic error.
+	 * - `11006` (`SHOP_FAILED_MAX_BOUGHT_ITEMS_REACHED`) — per-user purchase
+	 *   cap reached (e.g. "max 1 per day"). Surface the item's
+	 *   `limit_message` if set, otherwise `err_message`. Do not retry.
+	 * - `11007` — bonus was issued but a follow-up redemption step failed
+	 *   server-side. Funds **are** debited and the purchase event is recorded;
+	 *   the consumer's UI should refresh the store list (auto-refresh will
+	 *   fire) and surface a soft warning rather than a hard error.
+	 * - `11009` (`SHOP_FAILED_POOL_EMPTY`) — stock pool is empty / sold out.
+	 *   Show a "sold out" message; auto-refresh will mark the item as such
+	 *   in subsequent `getStoreItems()` updates.
+	 * - `11011` (`SHOP_NO_BALANCE_GEMS`) — insufficient **gems** balance.
+	 *   Same handling as `11000` but for the gems currency.
+	 * - `11012` (`SHOP_NO_BALANCE_DIAMONDS`) — insufficient **diamonds**
+	 *   balance. Same handling as `11000` but for the diamonds currency.
+	 * - `11014` (`SHOP_FAILED_PURCHASE_LIMITATION`) — outside the configured
+	 *   purchase window (purchase weekday / time-of-day / window). Surface
+	 *   the item's `purchase_limit_message` if set, otherwise `err_message`.
+	 * - `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.
+	 *
+	 * **Idempotency**: NOT idempotent. The server performs no de-duplication —
+	 * a second successful call deducts funds again and grants the reward
+	 * again (subject to per-user purchase caps). The SDK itself does **not**
+	 * enforce a single in-flight call. The consumer MUST guard the call site
+	 * against double-clicks (set a local "buying" flag on click, clear it on
+	 * response).
+	 *
+	 * **Refresh after success (and after failure)**
+	 * The SDK automatically re-fetches the store item list and the
+	 * purchased-items history on every response (success or error). Any
+	 * `onUpdate` callback registered via `getStoreItems({ onUpdate })` (or
+	 * the purchased-items equivalent) fires shortly after with the updated
+	 * arrays — reflecting the new `pool`, `can_buy`, and any `purchased_*`
+	 * flags. The user's balance (points / gems / diamonds) is exposed on the
+	 * user-properties channel and updates independently; if the UI displays
+	 * the balance, subscribe to user-property updates separately (it does
+	 * NOT flow through `getStoreItems`).
+	 *
+	 * **Side effects** (consumer-observable on success)
+	 * - User's points / gems / diamonds balance decreases by `price`
+	 *   (or `discounted_price` if set).
+	 * - Item's `pool` decrements by 1 (when `pool != null`).
+	 * - Per-user purchase counters update — `purchased_today`,
+	 *   `purchased_this_week`, `purchased_this_month` on the next
+	 *   `getStoreItems()` refresh.
+	 * - The reward is delivered: bonus issuance, mini-game spin grant,
+	 *   level change, prize drop, raffle ticket, or tangible-item record.
+	 *   Each reward type pushes its own follow-up update (e.g. a new
+	 *   bonus appears in `getBonuses()`, the spin shows up in
+	 *   `getMiniGames()`). Subscribe to each relevant channel separately.
+	 * - A purchase row is appended to the user's purchase history,
+	 *   surfaced via the purchased-items list.
+	 *
+	 * **UI guidance**: see [UI Guide — `buyStoreItem`](../../docs/ui/store/UIGuide_buyStoreItem.md).
+	 *
+	 * @param item_id  The store item `id` (from `getStoreItems()`).
+	 * @returns `{ err_code, err_message }`; success when `err_code === 0`.
+	 *
+	 * @example
+	 * ```ts
+	 * const items = await window._smartico.api.getStoreItems({
+	 *   onUpdate: (next) => console.log('[smartico] store items updated — re-render store grid with this fresh array', next),
+	 * });
+	 * const item = items.find(i => i.id === itemId);
+	 *
+	 * if (!item) {
+	 *   console.log('[smartico] item not in current store list — keep UI as-is, possibly refresh getStoreItems');
+	 *   return;
+	 * }
+	 *
+	 * // Local pre-checks: keep these aligned with the Buy-button decision matrix above.
+	 * const effectivePrice = item.discounted_price ?? item.price;
+	 * const inStock = item.pool == null || item.pool > 0;
+	 * const inWindow = !item.active_till_date || Date.now() < item.active_till_date;
+	 * if (!item.can_buy || !inStock || !inWindow) {
+	 *   console.log('[smartico] buy not applicable — show disabled state with operator copy if any:', item.cant_buy_message);
+	 *   return;
+	 * }
+	 *
+	 * console.log('[smartico] buy starting — set in-flight flag, show loading dots on Buy button, keep detail modal open');
+	 * const r = await window._smartico.api.buyStoreItem(item.id);
+	 * console.log('[smartico] buy response received — clear in-flight flag');
+	 *
+	 * if (r.err_code === 0) {
+	 *   console.log('[smartico] purchase successful — close the detail modal, show a success toast; getStoreItems onUpdate above will fire with the refreshed list (do NOT manually re-fetch)');
+	 * } else if (r.err_code === 11000 || r.err_code === 11011 || r.err_code === 11012) {
+	 *   console.error('[smartico] insufficient balance for this purchase_type — show insufficient-balance UI and how many units are missing:', item.purchase_type, effectivePrice);
+	 * } else if (r.err_code === 11009) {
+	 *   console.error('[smartico] item sold out — show a dedicated "Sold out" message; the auto-refresh will mark the card as such shortly');
+	 * } else if (r.err_code === 11006) {
+	 *   console.error('[smartico] per-user purchase cap reached — surface the operator-defined limit message:', item.limit_message || r.err_message);
+	 * } else if (r.err_code === 11014) {
+	 *   console.error('[smartico] outside purchase window — surface the operator-defined purchase-limit message:', item.purchase_limit_message || r.err_message);
+	 * } else if (r.err_code === 11004 || r.err_code === 11003) {
+	 *   console.error('[smartico] user not eligible / stale visibility — show a localized "try again later" message and let auto-refresh reconcile');
+	 * } else {
+	 *   console.error('[smartico] buy failed — show a generic error toast/modal with this message:', r.err_message);
+	 * }
+	 * ```
+	 */
+	public async buyStoreItem(item_id: number): Promise<TBuyStoreItemResult> {
+		const r = await this.api.buyStoreItem(this.userExtId, item_id);
+
+		const o: TBuyStoreItemResult = {
+			err_code: r.errCode,
+			err_message: r.errMsg,
+		};
+
+		return o;
+	}
+
+	/**
+	 * Returns the list of active store categories configured for the current label.
+	 * Categories are operator-defined groupings used to organize store items into tabs,
+	 * sections, or filter chips in the gamification store UI.
+	 *
+	 * @remarks
+	 * **What categories are**
+	 * - Operator-defined groupings, configured per-label by the brand operator.
+	 *   Only active categories are returned; inactive / archived / deleted ones are
+	 *   filtered out server-side.
+	 * - Each `TStoreCategory` exposes `{ id, name, order }`. `name` is the display label;
+	 *   `order` is the relative position (lower = appears first).
+	 * - The same set of categories is returned to every user of the label — there is no
+	 *   per-segment / per-currency / per-device filtering on the category list. Item-level
+	 *   segment visibility happens on {@link getStoreItems}, not here.
+	 *
+	 * **Localization / translation**
+	 * - `name` is **pre-translated server-side** to the authenticated user's stored language.
+	 *   In visitor mode, the language passed to `_smartico.vapi(lang)` drives the translation.
+	 *   Consumers never need to translate `name` themselves.
+	 * - Fallback if no translation exists for the user's language: the operator-set default
+	 *   (typically the brand's English) value is returned. The field is never null for an
+	 *   active category.
+	 *
+	 * **Sort order**
+	 * The server does NOT pre-sort. Sort client-side before rendering:
+	 * `categories.sort((a, b) => a.order - b.order)`.
+	 *
+	 * **How store items join to categories**
+	 * Each `TStoreItem` exposes `category_ids: number[]` (zero-or-more, many-to-many).
+	 * A single store item can belong to multiple categories, or to none. To render a
+	 * "category → items" view:
+	 * `items.filter(i => i.category_ids.includes(cat.id))`.
+	 *
+	 * **Uncategorized items**
+	 * Items with `category_ids: []` are NOT represented by a synthetic "Other" entry
+	 * in the response. The convention used by the reference store UI is to synthesize
+	 * a client-side bucket (e.g. labelled "General") for items that have no category, OR
+	 * for items whose `category_ids` reference a category that is no longer returned by
+	 * this method (e.g. archived since the item was tagged). If you choose to render
+	 * such a synthetic bucket, place it first (the reference UI uses an `order: -1`
+	 * convention so it precedes all operator-defined categories).
+	 *
+	 * **Empty categories**
+	 * A category may be returned even if zero items currently reference it (since this
+	 * method does not join against items). The reference store UI hides such empty
+	 * categories from its tab strip — replicate that filter if you don't want to render
+	 * tabs that lead to empty content panels.
+	 *
+	 * **Refresh cadence / cache**
+	 * - The SDK caches the response for 30 seconds. Subsequent calls within that window
+	 *   return the cached array without a network round-trip.
+	 * - The cache is NOT invalidated by store-item push events or purchases — operator-driven
+	 *   category changes propagate at the next 30 s cache miss.
+	 * - Cache is fully cleared on login / logout.
+	 * - In **visitor mode**, additional server-side caching applies on top of the SDK cache;
+	 *   worst-case staleness for an edited/added category is on the order of a few minutes
+	 *   for anonymous viewers.
+	 *
+	 * **Idempotency**: safe. Read-only metadata fetch. Cache de-duplicates concurrent calls.
+	 *
+	 * **Side effects**: none — pure metadata read.
+	 *
+	 * **UI guidance**: see [UI Guide — `getStoreCategories`](../../docs/ui/store/UIGuide_getStoreCategories.md).
+	 *
+	 * @returns Array of `{ id, name, order }`. Empty array if no active categories are
+	 *   configured for the label. `name` is pre-translated. Order is NOT applied — caller
+	 *   must sort.
+	 *
+	 * @example
+	 * ```ts
+	 * const [categories, items] = await Promise.all([
+	 *   window._smartico.api.getStoreCategories(),
+	 *   window._smartico.api.getStoreItems(),
+	 * ]);
+	 *
+	 * if (categories.length === 0) {
+	 *   console.log('[smartico] no store categories configured — render items as a flat grid without tabs:', items.length);
+	 * } else {
+	 *   // Sort categories; build per-category item buckets; hide empty categories
+	 *   const sorted = [...categories].sort((a, b) => a.order - b.order);
+	 *   const tabs = sorted
+	 *     .map(cat => ({ cat, items: items.filter(i => i.category_ids?.includes(cat.id)) }))
+	 *     .filter(t => t.items.length > 0);
+	 *
+	 *   // Optional: synthesize an "Other" bucket for items with no (or unknown) category
+	 *   const knownIds = new Set(categories.map(c => c.id));
+	 *   const orphans = items.filter(i => !i.category_ids?.length || !i.category_ids.some(id => knownIds.has(id)));
+	 *   if (orphans.length > 0) {
+	 *     console.log('[smartico] uncategorized store items — render a client-synthesized "Other" tab at the front of the tab strip:', orphans.length);
+	 *   }
+	 *
+	 *   console.log('[smartico] render store tabs in this order with these counts:', tabs.map(t => `${t.cat.name} (${t.items.length})`));
+	 * }
+	 *
+	 * // Visitor mode — same shape, language driven by vapi(lang) argument
+	 * const visitorCats = await window._smartico.vapi('DE').getStoreCategories();
+	 * console.log('[smartico] visitor-mode store categories (names translated to DE):', visitorCats);
+	 * ```
+	 */
+	public async getStoreCategories(): Promise<TStoreCategory[]> {
+		return OCache.use(
+			onUpdateContextKey.StoreCategories,
+			ECacheContext.WSAPI,
+			() => this.api.storeGetCategoriesT(this.userExtId),
+			CACHE_DATA_SEC,
+		);
+	}
+
+	/**
+	 * Fetches the authenticated user's **store purchase history** — a paginated,
+	 * newest-first list of past store purchases (one row per redemption).
+	 *
+	 * Designed for a "My Purchases" / "Order History" screen. Each entry carries
+	 * the same descriptive fields as the catalog card plus three history-only
+	 * fields: `purchase_ts` (when the purchase happened), `purchase_points_amount`
+	 * (the amount actually paid at that time — a price snapshot, not the
+	 * current `price`), and `purchase_type` (`'points' | 'gems' | 'diamonds'`).
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode is not supported (the SDK only
+	 *   exposes this method on the authenticated `_smartico.api`, not on
+	 *   `_smartico.vapi`).
+	 * - No prerequisite calls — calling without first fetching
+	 *   {@link getStoreItems} or {@link getStoreCategories} is fine.
+	 *
+	 * **Pagination semantics**
+	 * - **Offset-based**, newest-first. The server orders rows by purchase
+	 *   timestamp **descending** and the SDK does NOT re-sort — items arrive
+	 *   ready to render in display order.
+	 * - `limit` — page size. **The SDK default is 20.** There is no server-side
+	 *   hard cap, but 20 matches what the default Smartico UI uses end-to-end; the
+	 *   protocol and storage layers were sized for this page size. Treat `20`
+	 *   as the conventional/recommended value; passing a much larger limit will
+	 *   return more rows but is not the supported integration pattern.
+	 *   Avoid `limit <= 0` — the server peeks `limit + 1` rows internally, so
+	 *   `limit = 0` returns 1 row with a misleading "has more" signal, and
+	 *   negative values produce undefined results.
+	 * - `offset` — number of items to skip from the start. The SDK default is
+	 *   `0` (first page). For load-more pagination, pass
+	 *   `offset = (previously-loaded items).length` on each subsequent call.
+	 * - **No `hasMore` on the returned array.** `TStoreItem[]` is a flat list;
+	 *   the underlying protocol response carries `hasMore` but it is not
+	 *   surfaced through this method. Two ways for consumers to know they
+	 *   reached the end:
+	 *     1. The returned array is shorter than `limit` (definitive end), or
+	 *     2. A subsequent call at `offset = previous.length` returns `[]`.
+	 *   Either is reliable.
+	 * - No date-range / category / status filter parameters — pagination is the
+	 *   only server-side slicing. Apply any further filtering client-side.
+	 *
+	 * **No per-item fulfillment status**
+	 * - History entries do NOT carry a `delivered` / `pending` / `cancelled` /
+	 *   `refunded` field. The list contains rows for committed purchase
+	 *   attempts; the server query does not filter by transaction-status, so in
+	 *   practice the rows that appear are completed purchases (failed
+	 *   transactions roll back and don't write a row). Treat every item as a
+	 *   completed transaction unless a future SDK release adds an explicit
+	 *   status field.
+	 *
+	 * **Bonus-type entries**
+	 * - When the user redeemed a bonus item, the entry's `type` field surfaces
+	 *   as `'bonus'`. **Known limitation:** the SDK transform currently maps
+	 *   both `Bonus` and `Tangible` server-side item types to the same string
+	 *   `'bonus'` — so the `type` field on history rows cannot distinguish a
+	 *   bonus redemption from a tangible-prize redemption. The actual bonus
+	 *   payload (wallet credit, free spins, etc.) is dispatched by the server
+	 *   asynchronously and is NOT embedded in the history entry — consumers
+	 *   that need bonus details should subscribe to bonus push events
+	 *   separately rather than reading them from this list.
+	 * - History rows render identically across types — there is no deep-link to
+	 *   the bonus wallet or re-claim affordance on the row itself.
+	 *
+	 * **Per-row data**
+	 * Each row uses the `TStoreItem` shape but populates four history-only
+	 * fields not present on `getStoreItems` output. `purchase_ts` is the
+	 * Unix-ms timestamp of the purchase — format with
+	 * `new Date(purchase_ts).toLocaleString()` in the user's local timezone;
+	 * no relative labels ("Today" / "Yesterday") are produced by the SDK.
+	 * `purchase_points_amount` is the amount actually paid at the time of
+	 * purchase — a snapshot of the historical price, which may differ from
+	 * the item's current `price`. `purchase_type` is the currency actually
+	 * charged (`'points' | 'gems' | 'diamonds'`); render the matching
+	 * balance icon next to the amount. The convenience booleans
+	 * `purchased_today` / `purchased_this_week` / `purchased_this_month` are
+	 * computed client-side from the consumer's local clock — useful for
+	 * grouping rows under "Today" / "This Week" headers.
+	 *
+	 * **Catalog fields on a history row**
+	 * The promotional fields (`ribbon`, `discounted_price`,
+	 * `discount_price_ribbon`, `custom_ribbon_image`, `active_till_date`)
+	 * reflect the CURRENT catalog state of the item, NOT its state at
+	 * purchase time — the default Smartico UI hides them on history rows to
+	 * avoid implying that the historical purchase carried the current
+	 * promotional banner. Descriptive marketing fields (`description`,
+	 * `hint_text`, `related_games`) are typically suppressed on a compact
+	 * history row. The current-purchasability fields `can_buy` and `pool`
+	 * reflect now, not then — useful only if you render a "Buy Again"
+	 * affordance on the row. One implementation gotcha: unlike
+	 * `getStoreItems`, this method's transform does NOT auto-parse JSON
+	 * strings in `custom_data` — call `JSON.parse()` yourself if you store
+	 * JSON there.
+	 *
+	 * **Cache & refresh**
+	 * - The SDK caches each `(limit, offset)` page separately for 30 seconds.
+	 *   Repeated calls within that window resolve from cache without a
+	 *   network round-trip.
+	 * - The cache is invalidated and `onUpdate` (when registered) is invoked
+	 *   automatically after a successful {@link buyStoreItem} call — the SDK
+	 *   re-fetches the same page parameters that were registered together with
+	 *   the current `onUpdate` callback and pushes the fresh array.
+	 * - Multi-tab caveat: if the user has the same brand open in multiple
+	 *   tabs, **all open tabs** receive the `onUpdate` event on a purchase,
+	 *   not only the tab that initiated the buy. The event is scoped to the
+	 *   current authenticated user — a different user's purchase never fires
+	 *   this callback.
+	 * - Only ONE `onUpdate` callback can be registered at a time. Each call to
+	 *   `getStorePurchasedItems({ onUpdate })` overwrites the previous handler.
+	 *
+	 * **Idempotency**: safe. Pure read.
+	 *
+	 * **Side effects**: none — read-only.
+	 *
+	 * **UI guidance**: see [UI Guide — `getStorePurchasedItems`](../../docs/ui/store/UIGuide_getStorePurchasedItems.md).
+	 *
+	 * @param params - Optional pagination + callback bag.
+	 * @param params.limit - Page size. Defaults to `20`. Use `20` as the
+	 *   conventional value (matches the default Smartico UI end-to-end). Avoid
+	 *   non-positive values.
+	 * @param params.offset - Number of rows to skip from the newest end.
+	 *   Defaults to `0`. For load-more pagination pass the current array
+	 *   length.
+	 * @param params.onUpdate - Optional callback invoked after a successful
+	 *   {@link buyStoreItem} elsewhere in the session. Receives the refreshed
+	 *   page for the same `(limit, offset)` used on the call that registered
+	 *   this callback. Only ONE callback can be registered; each new call
+	 *   overwrites the previous one. Pass a stable handler or
+	 *   re-register intentionally on screen entry.
+	 *
+	 * @returns Promise resolving to an array of `TStoreItem` history entries
+	 *   in newest-first order. Empty array if the user has no purchases (or
+	 *   the requested `offset` is beyond the end). Each entry carries
+	 *   `purchase_ts`, `purchase_points_amount`, `purchase_type`, and the
+	 *   `purchased_today/this_week/this_month` convenience flags in addition
+	 *   to the standard item fields.
+	 *
+	 * @example
+	 * ```ts
+	 * // Initial load + subscribe to refresh-on-purchase.
+	 * const handleHistoryUpdate = (items: TStoreItem[]) => {
+	 *   console.log(
+	 *     '[smartico] purchase history refreshed — re-render the history list with these',
+	 *     items.length,
+	 *     'items (newest first):',
+	 *     items,
+	 *   );
+	 * };
+	 *
+	 * try {
+	 *   const firstPage = await _smartico.api.getStorePurchasedItems({
+	 *     limit: 20,
+	 *     offset: 0,
+	 *     onUpdate: handleHistoryUpdate,
+	 *   });
+	 *
+	 *   if (firstPage.length === 0) {
+	 *     console.log('[smartico] no purchase history — render the empty state ("No purchases yet")');
+	 *   } else {
+	 *     console.log(
+	 *       '[smartico] render',
+	 *       firstPage.length,
+	 *       'history rows (newest first). Show "Load more" button if length === 20:',
+	 *       firstPage,
+	 *     );
+	 *
+	 *     // Inspect the first entry's history-only fields.
+	 *     const first = firstPage[0];
+	 *     console.log(
+	 *       '[smartico] most-recent purchase: name=', first.name,
+	 *       'paid', first.purchase_points_amount, first.purchase_type,
+	 *       'at', new Date(first.purchase_ts ?? 0).toLocaleString(),
+	 *       '— format with toLocaleString (user-local time) on the row.',
+	 *     );
+	 *   }
+	 *
+	 *   // Load-more pattern: fetch page 2 once the user scrolls / clicks "Load more".
+	 *   if (firstPage.length === 20) {
+	 *     const nextPage = await _smartico.api.getStorePurchasedItems({
+	 *       limit: 20,
+	 *       offset: firstPage.length,
+	 *     });
+	 *     const isLastPage = nextPage.length < 20;
+	 *     console.log(
+	 *       '[smartico] appended page 2 —',
+	 *       nextPage.length,
+	 *       'rows.',
+	 *       isLastPage ? 'Hide "Load more" — end reached.' : 'Keep "Load more" visible.',
+	 *     );
+	 *   }
+	 * } catch (e) {
+	 *   console.error(
+	 *     '[smartico] failed to load purchase history — show a generic error placeholder or retry with backoff:',
+	 *     e,
+	 *   );
+	 * }
+	 * ```
+	 */
+	public async getStorePurchasedItems({
+		limit,
+		offset,
+		onUpdate,
+	}: { limit?: number; offset?: number; onUpdate?: (data: TStoreItem[]) => void } = {}): Promise<TStoreItem[]> {
+		const requestLimit = limit === undefined ? 20 : limit;
+		const requestOffset = offset === undefined ? 0 : offset;
+		const cacheKey = this.storeHistoryCacheKey(requestLimit, requestOffset);
+
+		if (onUpdate) {
+			this.onUpdateCallback.set(onUpdateContextKey.StoreHistory, onUpdate);
+			this.storeHistoryOnUpdateParams = { limit: requestLimit, offset: requestOffset };
+		}
+
+		return OCache.use(
+			cacheKey,
+			ECacheContext.WSAPI,
+			() => this.api.storeGetPurchasedItemsT(this.userExtId, requestLimit, requestOffset),
+			CACHE_DATA_SEC,
+		);
+	}
+
+	protected async updateStorePurchasedItems() {
+		const payload = await this.api.storeGetPurchasedItemsT(
+			this.userExtId,
+			this.storeHistoryOnUpdateParams.limit,
+			this.storeHistoryOnUpdateParams.offset,
+		);
+		const cacheKey = this.storeHistoryCacheKey(this.storeHistoryOnUpdateParams.limit, this.storeHistoryOnUpdateParams.offset);
+
+		OCache.set(cacheKey, payload, ECacheContext.WSAPI);
+
+		const onUpdate = this.onUpdateCallback.get(onUpdateContextKey.StoreHistory);
+		if (onUpdate) {
+			onUpdate(payload);
+		}
+	}
+
+	protected async updateStoreItems() {
+		const payload = await this.api.storeGetItemsT(this.userExtId);
+		this.updateEntity(onUpdateContextKey.StoreItems, payload);
+	}
+}