@smartico/public-api 0.0.378 → 0.0.380

package/docs/api/classes/WSAPIStore.md

@@ -0,0 +1,744 @@
+# Class: WSAPIStore
+## Methods
+
+### getStoreItems()
+
+> **getStoreItems**(`params?`): `Promise`\<[`TStoreItem`](../interfaces/TStoreItem.md)[]\>
+
+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.
+
+#### Parameters
+
+##### params?
+
+Optional. Omit to fetch without subscribing.
+
+###### onUpdate?
+
+(`data`) => `void`
+
+Callback invoked with the full refreshed
+                           catalog after every [buyStoreItem](#buystoreitem)
+                           round-trip on this connection. Each call to
+                           `getStoreItems` overwrites the prior
+                           callback. Never fires in visitor mode.
+
+#### Returns
+
+`Promise`\<[`TStoreItem`](../interfaces/TStoreItem.md)[]\>
+
+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).
+
+#### 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
+[getUserProfile](WSAPIUser.md#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 registered via `onUpdate` is invoked with the FULL refreshed
+catalog — never a diff/patch — after any `buyStoreItem(...)` call
+resolves on this connection (regardless of `err_code`). It is the ONLY
+trigger for the store catalog. Side effects covered:
+- Pool decrement on the item the user just bought.
+- `purchased_today` / `purchased_this_week` / `purchased_this_month`
+  flag flips (these appear only in the purchase-history list, but the
+  underlying `can_buy` field on the main catalog re-evaluates against
+  the operator's "max bought" rules after every purchase).
+- `can_buy === false` after a per-period purchase cap is hit.
+
+Each subsequent call to `getStoreItems({ onUpdate })` REPLACES the prior
+callback — there is 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.
+
+**What does NOT trigger an `onUpdate`** (consumer-relevant)
+- Operator-side BO catalog edits (price, ribbons, pool seed, segment
+  conditions, new/removed items) do NOT push to connected clients —
+  those changes surface only on the next cache miss.
+- Pool depletion caused by OTHER users' concurrent purchases does NOT
+  push. The current user's view of `pool` may be stale until they
+  trigger a refresh themselves.
+- User balance changes (points/gems/diamonds going up from gameplay)
+  do NOT refresh the catalog. The catalog is independent of balance;
+  the consumer must drive button affordability from a separately
+  tracked balance source (e.g. the user's gamification profile,
+  updated independently of this catalog).
+- Items going past their `active_till_date` while the page is open do
+  NOT push — the item will simply disappear 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 with `shop_pool_hide_when_empty = true` whose pool has reached 0
+  (operator-configured per item). 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).
+
+**Field semantics** (non-obvious fields on `TStoreItem`)
+- `price` is typed as `number` on the SDK surface; internally the server
+  stores it as a string and the SDK converts. Always coerce defensively
+  if you arithmetic against it.
+- `purchase_type` is per-item and may differ across items in the same
+  catalog: `'points'`, `'gems'`, or `'diamonds'`. There is no
+  label-level currency — operators can mix currencies freely.
+- `can_buy` reflects segment conditions, per-period purchase caps, and
+  item-active-window — but NOT the user's current balance. Consumers
+  must check affordability separately by comparing `price` to the
+  live balance for `purchase_type`.
+- `pool` is `null` for unlimited items, a positive integer for limited
+  stock, and `0` for sold-out items that the operator kept visible. It
+  is NOT live: only the buyer's own pool-decrementing purchase updates
+  it client-side.
+- `active_till_date` is a unix-ms timestamp; items past this point are
+  filtered server-side, so consumers should NOT need to render an
+  "Expired" state for catalog items (only for purchase-history rows).
+  A live countdown ("flash sale ends in HH:MM:SS") is rendered only
+  when the operator has enabled the per-item `show_timer` flag.
+- `discounted_price` + `discount_price_ribbon` are the discount-display
+  pair: render `price` with a strikethrough and `discounted_price` as
+  the active price. `discount_price_ribbon` is either a percentage
+  preset (`'10'`, `'15'`, `'20'`, `'25'`, `'50'`) styled by the
+  consumer's CSS, or the literal `'custom'` — in which case
+  `custom_ribbon_image` (250×300 px URL) is the artwork.
+- `ribbon` (general item ribbon) accepts the presets `'sale'`, `'hot'`,
+  `'new'`, `'vip'` (built-in styling) or a custom-image URL (250×300 px).
+- `category_ids` maps to `TStoreCategory.id` from
+  [getStoreCategories](#getstorecategories) — an item can appear in multiple categories;
+  render it as multiple cards or once per active-tab as the consumer's
+  navigation prefers.
+- `only_in_custom_section: true` means the item should be HIDDEN from
+  the main store view and shown only inside the operator-defined
+  custom section (`custom_section_id`). The catalog still includes it —
+  filter client-side for general views.
+- `type` distinguishes the post-purchase server effect (see "Side
+  effects" below). UI rendering of the CATALOG card is identical across
+  types — there is no built-in card variation per type.
+- `purchase_ts`, `purchase_points_amount`, `purchased_today`,
+  `purchased_this_week`, `purchased_this_month` are populated only on
+  rows returned from [getStorePurchasedItems](#getstorepurchaseditems) (purchase history),
+  NOT on rows from `getStoreItems`.
+
+**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
+  [getBonuses](#getbonuses).
+- `type = 'raffleticket'` → raffle tickets granted; surfaces via
+  `getRaffles`.
+- `type = 'changelevel'` → user's level adjusted; surfaces via
+  [getCurrentLevel](WSAPIUser.md#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`](../../ui/store/UIGuide_getStoreItems.md).
+
+#### 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');
+```
+
+***
+
+### buyStoreItem()
+
+> **buyStoreItem**(`item_id`): `Promise`\<[`TBuyStoreItemResult`](../interfaces/TBuyStoreItemResult.md)\>
+
+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.
+
+#### Parameters
+
+##### item\_id
+
+`number`
+
+The store item `id` (from `getStoreItems()`).
+
+#### Returns
+
+`Promise`\<[`TBuyStoreItemResult`](../interfaces/TBuyStoreItemResult.md)\>
+
+`{ err_code, err_message }`; success when `err_code === 0`.
+
+#### 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`](../../ui/store/UIGuide_buyStoreItem.md).
+
+#### 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);
+}
+```
+
+***
+
+### getStoreCategories()
+
+> **getStoreCategories**(): `Promise`\<[`TStoreCategory`](../interfaces/TStoreCategory.md)[]\>
+
+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.
+
+#### Returns
+
+`Promise`\<[`TStoreCategory`](../interfaces/TStoreCategory.md)[]\>
+
+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.
+
+#### 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 [getStoreItems](#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`](../../ui/store/UIGuide_getStoreCategories.md).
+
+#### 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);
+```
+
+***
+
+### getStorePurchasedItems()
+
+> **getStorePurchasedItems**(`params?`): `Promise`\<[`TStoreItem`](../interfaces/TStoreItem.md)[]\>
+
+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'`).
+
+#### Parameters
+
+##### params?
+
+Optional pagination + callback bag.
+
+###### limit?
+
+`number`
+
+Page size. Defaults to `20`. Use `20` as the
+  conventional value (matches the default Smartico UI end-to-end). Avoid
+  non-positive values.
+
+###### offset?
+
+`number`
+
+Number of rows to skip from the newest end.
+  Defaults to `0`. For load-more pagination pass the current array
+  length.
+
+###### onUpdate?
+
+(`data`) => `void`
+
+Optional callback invoked after a successful
+  [buyStoreItem](#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`\<[`TStoreItem`](../interfaces/TStoreItem.md)[]\>
+
+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.
+
+#### 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
+  [getStoreItems](#getstoreitems) or [getStoreCategories](#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.
+
+**History-only fields on `TStoreItem`**
+The following fields are populated **only** for entries returned by this
+method (NOT by [getStoreItems](#getstoreitems)):
+- `purchase_ts` — Unix milliseconds, server-recorded UTC moment of
+  purchase. Format on the consumer side in the **user's browser local
+  timezone** (the default Smartico UI uses
+  `new Date(purchase_ts).toLocaleString(undefined, { dateStyle: 'short', timeStyle: 'medium' })`).
+  No relative labels ("Today" / "Yesterday") are produced by the SDK —
+  render those client-side if desired.
+- `purchase_points_amount` — the amount the user actually paid at the
+  time of purchase, in the currency given by `purchase_type`. Historical
+  discounts are preserved here; the item's current `price` may differ.
+- `purchase_type` — `'points' | 'gems' | 'diamonds'`. The currency
+  actually charged. Render the matching balance icon next to
+  `purchase_points_amount`.
+- `purchased_today` / `purchased_this_week` / `purchased_this_month` —
+  convenience booleans computed by the SDK at transform time using the
+  **consumer's local clock**, not server-stamped. Useful for client-side
+  bucketing (e.g. "Today" / "This Week" group headers).
+
+**Catalog fields that ARE present but commonly ignored on a history row**
+- `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 mis-implying that
+  the historical purchase carried that current promotional banner.
+- `description`, `hint_text` (T&C), `related_games` — descriptive
+  marketing fields; typically suppressed on a compact history row.
+- `can_buy`, `pool` — reflect **current** purchasability of the same
+  item, useful only if you render a "Buy Again" affordance on the history
+  row (see UI guidance below).
+- `custom_data` — present, but unlike `getStoreItems` the history
+  transform does NOT auto-parse JSON strings. If you store JSON there,
+  call `JSON.parse()` yourself.
+
+**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 [buyStoreItem](#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`](../../ui/store/UIGuide_getStorePurchasedItems.md).
+
+#### 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,
+  );
+}
+```
+
+***