# 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 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
[getStorePurchasedItems](#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 [getUserProfile](WSAPIUser.md#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
[getStoreCategories](#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
[getStorePurchasedItems](#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
  [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.

**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 [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,
  );
}
```

***