@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/getStoreCategories.md

@@ -0,0 +1,128 @@
+# getStoreCategories — API (TStoreCategory)
+
+> Returns the list of active store categories configured for the current label.
+> Import: `import { TStoreCategory } from '@smartico/public-api'`
+> Search terms: getStoreCategories, store, TStoreCategory, id, name, order
+
+## Signature
+```ts
+_smartico.api.getStoreCategories(): Promise<TStoreCategory[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TStoreCategory[]>`
+Array of `TStoreCategory`. Each item:
+- `id` (number) — ID of the store category
+- `name` (string) — Name of the store category
+- `order` (number) — Order of the store category among other categories. Default value is 1
+
+## Behavioral contract
+**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`, 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).
+
+## 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);
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+[
+  {
+    "id": 568,
+    "name": "Currency",
+    "order": 7
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getStoreItems`

package/docs/capabilities/getStoreItems.md

@@ -0,0 +1,260 @@
+# getStoreItems — API (TStoreItem)
+
+> Returns the catalog of buyable store items visible to the current user, scoped server-side to what the user is qualified to see.
+> Import: `import { TStoreItem } from '@smartico/public-api'`
+> Search terms: getStoreItems, store, TStoreItem, TRibbon, AchRelatedGame, onUpdate, subscription, id, name, purchase_type, price, image, description, ribbon, priority
+
+## Signature
+```ts
+_smartico.api.getStoreItems({ onUpdate }: { onUpdate?: (data: TStoreItem[]) => void } = {}): Promise<TStoreItem[]>
+```
+
+## Parameters
+- `params` — Optional. Omit to fetch without subscribing.
+- `params.onUpdate` — Callback invoked with the full refreshed catalog after every `buyStoreItem`round-trip on this connection. Each call to `getStoreItems` overwrites the prior callback. Never fires in visitor mode.
+
+## Returns — `Promise<TStoreItem[]>`
+Array of `TStoreItem`. Each item:
+- `id` (number) — ID of the store item
+- `name` (string) — Name of the store item, translated to the user language
+- `description` (string) — Description of the store item, translated to the user language
+- `image` (string) — URL of the image of the store item, 256x256px
+- `type` ('bonus' | 'tangible' | 'minigamespin' | 'changelevel' | 'prizedrop' | 'unknown' | 'raffleticket') — Type of the store item. Can be 'bonus' or 'tangible' or different others.
+- `price` (number) — The price of the store item in the gamification points
+- `ribbon` (TRibbon) — The ribbon of the store item. Can be 'sale', 'hot', 'new', 'vip' or URL to the image in case of custom ribbon, 250x300px
+- `limit_message` (string) — The message that should be shown to the user if he is not eligible to buy it. this message can be used to explain the reason why user cannot buy the item, e.g. 'You should be VIP to buy this item' and can be used in case can_buy property is false. The message is translated to the user language. *Note**: when user is trying to buy the item, the response from server can return custom error messages that can be shown to the user as well
+- `purchase_limit_message` (string) — The message that should be shown to the user if they are not eligible to buy it because of purchase limitation. This message can be used to explain the reason why user cannot buy the item, e.g. 'Item is no more available today. Come back Friday'. The message is translated to the user language. *Note**: when user is trying to buy the item, the response from server can return custom error messages that can be shown to the user as well
+- `priority` (number) — The priority of the store item. Can be used to sort the items in the store
+- `related_item_ids` (number[]) — The list of IDs of the related items. Can be used to show the related items in the store
+- `related_games` (AchRelatedGame[]) — List of casino games (or other types of entities) related to the store item
+  - `ext_game_id` (string) — The ID of the related game
+  - `game_public_meta` ({
+		/** The name of the game */
+		name: string;
+		/** The URL to the game */
+		link: string;
+		/** The URL to the image of the game, 1:1 aspect ratio */
+		image: string;
+		/** The indicator if the game is enabled */
+		enabled: boolean;
+		/** The list of categories of the game */
+		game_categories: string[];
+		/** The name of the game provider */
+		game_provider: string;
+		/** The URL to the mobile game */
+		mobile_spec_link: string;
+		/** The priority of the game */
+		priority?: number;
+	}) — Game public meta information
+- `can_buy` (boolean) — The indicator if the user can buy the item This indicator is taking into account the segment conditions for the store item, the price of item towards users balance,
+- `category_ids` (number[]) — The list of IDs of the categories where the store item is assigned, information about categories can be retrieved with getStoreCategories method
+- `pool` (number) — Items remaining in the pool available for purchase. `null` = unlimited supply. Positive integer = remaining stock. `0` = sold out but still returned (operator may instead hide pool-empty items entirely).
+- `custom_data` (any) — The custom data of the store item defined by operator. Can be a JSON object, string or number
+- `hint_text` (string) — The T&C text for the store item
+- `purchase_ts` (number) — Purchase time to show in purchase history screen
+- `purchase_points_amount` (number) — The amount of points you can purchase an item
+- `purchased_today` (boolean) — Flag for store item indicating that it was purchased today
+- `purchased_this_week` (boolean) — Flag for store item indicating that it was purchased this week
+- `purchased_this_month` (boolean) — Flag for store item indicating that it was purchased this month
+- `purchase_type` ('points' | 'gems' | 'diamonds') — The type of the purchase
+- `active_till_date` (number) — The date when the store item will be available till
+- `show_timer` (boolean) — Should countdown timer be shown when `active_till_date` is present
+- `discounted_price` (number) — The discounted price of the store item
+- `discount_price_ribbon` (string) — The ribbon of the discounted price.
+- `custom_ribbon_image` (string) — The custom ribbon image of the discounted price, 250x300px
+- `custom_section_id` (number) — The ID of the custom section where the store item is assigned
+- `only_in_custom_section` (boolean) — The indicator if the store item is visible only in the custom section and should be hidden from the main overview of store items
+- `custom_section_type_id` (number) — ID of specific Custom Section type
+- `cant_buy_message` (string) — The message that should be shown to the user if they are not eligible to buy it. This message can be used to explain the reason why user cannot buy the item, e.g. 'You should be VIP to buy this item'.
+
+## Behavioral contract
+**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`) 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`.
+
+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`). `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` (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`, 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`.
+- `type = 'raffleticket'` → raffle tickets granted; surfaces via
+ `getRaffles`.
+- `type = 'changelevel'` → user's level adjusted; surfaces via
+ `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).
+
+## 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');
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+[
+  {
+    "id": 7771,
+    "name": "Do not the cat",
+    "purchase_type": "points",
+    "price": 69,
+    "image": "https://cdn.example/83109b74be861920197eb8-cat-space.gif",
+    "description": "Please do not the cat",
+    "ribbon": "hot",
+    "priority": 10,
+    "type": "unknown",
+    "can_buy": false,
+    "category_ids": [
+      234
+    ],
+    "pool": 69,
+    "custom_data": {},
+    "active_till_date": 9223372036854776000,
+    "show_timer": false,
+    "only_in_custom_section": false,
+    "cant_buy_message": "Please do not the cat. Thank you.",
+    "related_games": []
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getUserProfile`
+- `getStorePurchasedItems`
+- `getStoreCategories`
+- `getBonuses`
+- `getCurrentLevel`
+- `buyStoreItem`

package/docs/capabilities/getStorePurchasedItems.md

@@ -0,0 +1,280 @@
+# getStorePurchasedItems — API (TStoreItem)
+
+> Fetches the authenticated user's **store purchase history** — a paginated, newest-first list of past store purchases (one row per redemption).
+> Import: `import { TStoreItem } from '@smartico/public-api'`
+> Search terms: getStorePurchasedItems, store, TStoreItem, TRibbon, AchRelatedGame, onUpdate, subscription, id, name, price, purchase_type, image, description, ribbon, priority
+
+## Signature
+```ts
+_smartico.api.getStorePurchasedItems({
+		limit,
+		offset,
+		onUpdate,
+	}: { limit?: number; offset?: number; onUpdate?: (data: TStoreItem[]) => void } = {}): Promise<TStoreItem[]>
+```
+
+## Parameters
+- `params` — - Optional pagination + callback bag.
+- `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.
+- `params.offset` — - Number of rows to skip from the newest end. Defaults to `0`. For load-more pagination pass the current array length.
+- `params.onUpdate` — - Optional callback invoked after a successful `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[]>`
+Array of `TStoreItem`. Each item:
+- `id` (number) — ID of the store item
+- `name` (string) — Name of the store item, translated to the user language
+- `description` (string) — Description of the store item, translated to the user language
+- `image` (string) — URL of the image of the store item, 256x256px
+- `type` ('bonus' | 'tangible' | 'minigamespin' | 'changelevel' | 'prizedrop' | 'unknown' | 'raffleticket') — Type of the store item. Can be 'bonus' or 'tangible' or different others.
+- `price` (number) — The price of the store item in the gamification points
+- `ribbon` (TRibbon) — The ribbon of the store item. Can be 'sale', 'hot', 'new', 'vip' or URL to the image in case of custom ribbon, 250x300px
+- `limit_message` (string) — The message that should be shown to the user if he is not eligible to buy it. this message can be used to explain the reason why user cannot buy the item, e.g. 'You should be VIP to buy this item' and can be used in case can_buy property is false. The message is translated to the user language. *Note**: when user is trying to buy the item, the response from server can return custom error messages that can be shown to the user as well
+- `purchase_limit_message` (string) — The message that should be shown to the user if they are not eligible to buy it because of purchase limitation. This message can be used to explain the reason why user cannot buy the item, e.g. 'Item is no more available today. Come back Friday'. The message is translated to the user language. *Note**: when user is trying to buy the item, the response from server can return custom error messages that can be shown to the user as well
+- `priority` (number) — The priority of the store item. Can be used to sort the items in the store
+- `related_item_ids` (number[]) — The list of IDs of the related items. Can be used to show the related items in the store
+- `related_games` (AchRelatedGame[]) — List of casino games (or other types of entities) related to the store item
+  - `ext_game_id` (string) — The ID of the related game
+  - `game_public_meta` ({
+		/** The name of the game */
+		name: string;
+		/** The URL to the game */
+		link: string;
+		/** The URL to the image of the game, 1:1 aspect ratio */
+		image: string;
+		/** The indicator if the game is enabled */
+		enabled: boolean;
+		/** The list of categories of the game */
+		game_categories: string[];
+		/** The name of the game provider */
+		game_provider: string;
+		/** The URL to the mobile game */
+		mobile_spec_link: string;
+		/** The priority of the game */
+		priority?: number;
+	}) — Game public meta information
+- `can_buy` (boolean) — The indicator if the user can buy the item This indicator is taking into account the segment conditions for the store item, the price of item towards users balance,
+- `category_ids` (number[]) — The list of IDs of the categories where the store item is assigned, information about categories can be retrieved with getStoreCategories method
+- `pool` (number) — Items remaining in the pool available for purchase. `null` = unlimited supply. Positive integer = remaining stock. `0` = sold out but still returned (operator may instead hide pool-empty items entirely).
+- `custom_data` (any) — The custom data of the store item defined by operator. Can be a JSON object, string or number
+- `hint_text` (string) — The T&C text for the store item
+- `purchase_ts` (number) — Purchase time to show in purchase history screen
+- `purchase_points_amount` (number) — The amount of points you can purchase an item
+- `purchased_today` (boolean) — Flag for store item indicating that it was purchased today
+- `purchased_this_week` (boolean) — Flag for store item indicating that it was purchased this week
+- `purchased_this_month` (boolean) — Flag for store item indicating that it was purchased this month
+- `purchase_type` ('points' | 'gems' | 'diamonds') — The type of the purchase
+- `active_till_date` (number) — The date when the store item will be available till
+- `show_timer` (boolean) — Should countdown timer be shown when `active_till_date` is present
+- `discounted_price` (number) — The discounted price of the store item
+- `discount_price_ribbon` (string) — The ribbon of the discounted price.
+- `custom_ribbon_image` (string) — The custom ribbon image of the discounted price, 250x300px
+- `custom_section_id` (number) — The ID of the custom section where the store item is assigned
+- `only_in_custom_section` (boolean) — The indicator if the store item is visible only in the custom section and should be hidden from the main overview of store items
+- `custom_section_type_id` (number) — ID of specific Custom Section type
+- `cant_buy_message` (string) — The message that should be shown to the user if they are not eligible to buy it. This message can be used to explain the reason why user cannot buy the item, e.g. 'You should be VIP to buy this item'.
+
+## Behavioral contract
+**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` or `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` 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).
+
+## 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,
+  );
+}
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+[
+  {
+    "id": 7158,
+    "name": "Okayish Drop",
+    "price": 25,
+    "purchase_type": "points",
+    "image": "https://cdn.example/33fa1a793eac4a807041ac-Gamificationpoints10.webp",
+    "description": "A chance to win one out of 6 totally fine prizes",
+    "ribbon": "sale",
+    "priority": 3,
+    "type": "prizedrop",
+    "can_buy": true,
+    "category_ids": [
+      567
+    ],
+    "pool": 1000,
+    "purchase_ts": 1781880583706,
+    "purchase_points_amount": 25,
+    "purchased_today": false,
+    "purchased_this_week": false,
+    "purchased_this_month": true,
+    "show_timer": false,
+    "related_games": []
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getStoreItems`
+- `getStoreCategories`
+- `buyStoreItem`