@smartico/public-api 0.0.379 → 0.0.380

package/dist/WSAPI/WSAPIStore.d.ts

@@ -0,0 +1,656 @@
+import { TBuyStoreItemResult, TStoreCategory, TStoreItem } from './WSAPITypes';
+import { WSAPIBonuses } from './WSAPIBonuses';
+/** @group Store */
+export declare class WSAPIStore extends WSAPIBonuses {
+    private storeHistoryOnUpdateParams;
+    private storeHistoryCacheKey;
+    /**
+     * 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');
+     * ```
+     */
+    getStoreItems({ onUpdate }?: {
+        onUpdate?: (data: TStoreItem[]) => void;
+    }): Promise<TStoreItem[]>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    buyStoreItem(item_id: number): Promise<TBuyStoreItemResult>;
+    /**
+     * 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);
+     * ```
+     */
+    getStoreCategories(): Promise<TStoreCategory[]>;
+    /**
+     * 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,
+     *   );
+     * }
+     * ```
+     */
+    getStorePurchasedItems({ limit, offset, onUpdate, }?: {
+        limit?: number;
+        offset?: number;
+        onUpdate?: (data: TStoreItem[]) => void;
+    }): Promise<TStoreItem[]>;
+    protected updateStorePurchasedItems(): Promise<void>;
+    protected updateStoreItems(): Promise<void>;
+}