@smartico/public-api 0.0.379 → 0.0.381

package/docs/ui/user/UIGuide_getActivityLog.md

@@ -0,0 +1,130 @@
+# UI Guide — `getActivityLog`
+
+## Overview
+- Returns the user's unified balance-change history — every points / gems /
+  diamonds transaction in the requested window, newest-first.
+- Power an "Activity" / "History" tab showing wins, claims, purchases,
+  level-up rewards, and operator adjustments.
+- 30 s SDK cache + push refresh on every wallet change (with a caveat —
+  see below).
+
+## List view organization
+
+Single flat list, server-sorted newest-first by `create_date`. The default
+Smartico UI groups rows visually by calendar day (e.g. "Today", "Yesterday",
+"24 May").
+
+### Time-period filter chips
+
+The default Smartico UI exposes these filters on top:
+
+| Chip | `startTimeSeconds` | `endTimeSeconds` |
+|---|---|---|
+| Today | today 00:00 local | now + 60 s |
+| This week | Monday 00:00 local | now + 60 s |
+| Previous week | Prev Monday 00:00 | Prev Sunday 23:59:59 |
+| Last 24 h (default) | now − 86400 | now + 60 s |
+
+Custom UIs can pick any window; the server scans the full range.
+
+## Item card / row
+
+Fields rendered per row:
+
+| Field | Source | Notes |
+|---|---|---|
+| Currency icon | `type` (`UserBalanceType`) | points / gems / diamonds icon |
+| Amount | `amount` | Prepend `+` if positive; color green when `>= 0`, red when negative |
+| Balance after | `balance` | Right-aligned column |
+| Source label | `source_type_id` (`PointChangeSourceType`) | See mapping table below |
+| Timestamp | `create_date` (epoch s × 1000) | Relative ("2h ago") or HH:MM |
+
+## Source label mapping
+
+For consistency with the default Smartico UI, group source IDs into these
+display buckets:
+
+| `PointChangeSourceType` | Display label |
+|---|---|
+| `Journey` (1), `ManualAdjustment` (6), `AutomationRule` (12), `API` (18) | "Marketing" |
+| `AchievementTaskCompletion` (2) | "Mission Task" |
+| `AchievementCompletion` (3) | "Mission" |
+| `LevelsStructureChange` (4) | "Level" |
+| `StorePurchase` (5) | "Store" |
+| `Leaderboard` (7) | "Leaderboard" |
+| `Tournament` (11), `TournamentRegistration` (13), `TournamentRegistrationCancellation` (14) | "Tournament" |
+| `RefundPoints` (15) | "Refund" |
+| `PlayMiniGame` (16), `WinMiniGame` (17) | "Mini-Game" |
+| `DynamicFormula` (19) | "Formula" |
+| `Raffle` (21) | "Raffle" |
+| `Avatars` (22) | "Avatar" |
+| *(any unknown)* | "Other" |
+
+## Pagination
+
+`from` and `to` are offset + ceiling, NOT timestamps:
+
+- `offset = from`
+- `limit = min(to - from, 50)` — server hard-caps at 50 rows per request.
+
+For infinite scroll, advance `from` by 50 each page. Detect end of list when
+the returned array length is less than the requested page size.
+
+## Subscription model — `onUpdate` caveat
+
+The `onUpdate` callback fires whenever the user's points / gems / diamonds
+balance changes. **The pushed payload is a FIXED re-fetch** of:
+
+- `startTimeSeconds = now - 600` (last 10 minutes)
+- `endTimeSeconds = now`
+- `from = 0`, `to = 50`
+
+It does NOT use the original call's parameters. Consumers maintaining a long
+historical view (e.g. 30 days) should treat `onUpdate` as a "new transactions
+arrived" hint and re-call `getActivityLog` with their own params:
+
+```ts
+const log = await window._smartico.api.getActivityLog({
+  startTimeSeconds: thirtyDaysAgo,
+  endTimeSeconds:   now,
+  from: 0, to: 50,
+  onUpdate: async (refreshed) => {
+    console.log('[smartico] wallet changed — refreshed last-10-min payload arrived');
+    // To keep the 30-day view current, re-fetch with the original params:
+    const fresh = await window._smartico.api.getActivityLog({
+      startTimeSeconds: thirtyDaysAgo,
+      endTimeSeconds: Math.floor(Date.now() / 1000),
+      from: 0, to: 50,
+    });
+    console.log('[smartico] re-rendered full 30-day list with', fresh.length, 'rows');
+  },
+});
+```
+
+## Empty / loading / error states
+
+- **Empty**: "No activity in this period" — common for new users or
+  narrow time windows.
+- **Loading (cold fetch)**: skeleton list (5 placeholder rows).
+- **Error**: keep prior list if any; non-blocking banner.
+
+## Refresh
+
+- 30 s SDK cache absorbs rapid tab switches.
+- Push triggers fire on every wallet change; the SDK handles invalidation
+  internally.
+- For the user's CURRENT balance (not the activity log), read
+  [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile) — the
+  activity log is for historical detail, not for the current balance widget.
+
+## Mobile vs desktop
+
+- **Desktop**: row shows activity icon · source label · amount · balance · time.
+- **Mobile**: row stacks activity + source label on the left, amount + balance
+  on the right.
+
+## Performance
+
+- 30 s cache + push invalidation makes repeated tab opens cheap.
+- 50-row page limit — paginate via `from` for full history.
+- Don't poll — the `onUpdate` callback handles change detection.

package/docs/ui/user/UIGuide_getLevels.md

@@ -0,0 +1,167 @@
+# UI Guide — `getLevels`
+
+## Overview
+
+- Returns the full level ladder for the label — one `TLevel` per
+active level, server-sorted by `required_points` ASC.
+- Use as a lookup table to resolve `ach_level_current_id` from
+`[getUserProfile](../../api/classes/WSAPIUser.md#getuserprofile)`
+into a richer level object, or as the source for a level map UI.
+- Loading indicator: skip on cache hit (30 s); show a brief shimmer
+on cold fetch (typically 100–300 ms).
+
+## List view organization
+
+The default Smartico UI renders levels as a **vertical grid** —
+2-column on mobile (`grid-boxes-2 levels`), responsive on desktop
+(`grid-boxes-levels`). No horizontal-scroll layout, no tabs.
+
+Items are already sorted by `required_points` ASC; `ordinal_position`
+is a 1-based index matching that sort. Render in the returned array
+order — no client-side sort needed unless your label uses
+sliding-window leveling (then sort secondary on
+`required_level_counter_1`, then `required_level_counter_2`).
+
+## Client-side filtering by `visibility_points`
+
+The server returns ALL active levels; the default Smartico UI hides
+levels the user hasn't reached the visibility threshold for:
+
+```ts
+const visible = levels.filter(l =>
+  l.visibility_points == null || l.visibility_points <= profile.ach_points_ever
+);
+```
+
+Hidden levels are absent from the render entirely — no "?" tile, no
+silhouette. If your product surface wants a teaser for upcoming
+levels, render the hidden ones with a custom CSS treatment instead
+of filtering them out.
+
+## Level tile
+
+Fields rendered per tile:
+
+
+| Field              | Use                                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------------------- |
+| `image`            | Tile icon (square, 256×256 px source).                                                               |
+| `name`             | Tile heading.                                                                                        |
+| `description`      | Optional sub-text under the heading; the default UI shows this in the detail modal, not on the tile. |
+| `required_points`  | Threshold display: `"{N} pts to reach"` or progress bar.                                             |
+| `ordinal_position` | Tile order; matches array order.                                                                     |
+
+
+**Locked vs unlocked treatment** — apply a `disabled` class to tiles
+where the user hasn't met the threshold:
+
+- Points-only leveling (most labels): `disabled = ach_points_ever < required_points`
+- Sliding-window leveling: also check
+`level_counter_1 < required_level_counter_1` (and `_2`) from
+`[getUserLevelExtraCounters](../../api/classes/WSAPIUser.md#getuserlevelextracounters)`.
+- Manual-only leveling: `disabled` unless the level matches the
+user's current `ach_level_current_id`.
+
+The default Smartico UI uses CSS-only treatment for locked tiles —
+no padlock icon, no greyscale by default. Brands can add those via
+custom CSS / Liquid skin overrides.
+
+## Detail view (per-level modal)
+
+When the user taps a tile, open a modal showing:
+
+- Hero image (`image`)
+- Title (`name`), description (`description`)
+- Progress block: for the user's current level, three stacked
+progress bars (points / counter 1 / counter 2) — see "Sliding-window
+leveling" below. For other levels, just the requirement display.
+- Custom fields rendered from `custom_data` (operator-defined).
+
+`custom_data` is typed as `string` but at runtime is `any` — the SDK
+auto-parses JSON-looking strings. Always guard with
+`typeof custom_data === 'object'` before property access; treat
+non-object values as raw strings.
+
+## Sliding-window leveling (advanced)
+
+If your label uses sliding-window leveling (the "Logic 2" model), the
+`required_level_counter_1` and `required_level_counter_2` fields are
+populated. Render alongside the points threshold:
+
+```
+Points:    {ach_points_ever} / {required_points}
+Counter 1: {level_counter_1} / {required_level_counter_1}   ← from getUserLevelExtraCounters
+Counter 2: {level_counter_2} / {required_level_counter_2}
+```
+
+The operator names the counters via translation keys
+(`levelsCounter1Name`, `levelsCounter2Name`) — typical values are
+"Total Deposits", "Total Wagering", etc. The SDK does not expose the
+operator's chosen labels; resolve them via
+`[getTranslations](../../api/classes/WSAPIGeneral.md#gettranslations)`.
+
+On points-only labels, both `required_level_counter_*` fields are
+`null` — skip rendering the counter rows.
+
+## Progress to next level
+
+Two formulas are in use; pick whichever fits your design:
+
+- **From-zero (default Smartico UI uses this)**:
+`ach_points_ever / next_level.required_points × 100`. Shows
+"absolute" progress; never decreases as the user gains points.
+- **From-current-level-floor (SDK uses this in
+`[getCurrentLevel](../../api/classes/WSAPIUser.md#getcurrentlevel)`)**:
+`(ach_points_ever − current.required_points) / (next.required_points − current.required_points) × 100`. Resets to 0 when the user levels
+up; better for "how far through this level" UX.
+
+Both bound at 100; at the max level the bar shows full.
+
+## Image / asset specs
+
+
+| Field   | Aspect                                     | Notes                                                                                                  |
+| ------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `image` | 1:1 (square), 256×256 px documented source | Render in a square tile container; fallback: text-only tile with the level name if `image` is missing. |
+
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: render a skeleton grid (3–6 placeholder
+tiles) sized to the eventual layout.
+- **Loading (cache hit)**: do not render a loading state — the
+promise resolves within a microtask.
+- **Empty result**: `[]` means no levels are configured for the
+label. Hide the level UI entirely (or render a neutral
+"no levels configured" placeholder).
+- **Error**: keep the prior list visible if any; show a small
+non-blocking error banner; retry on next user-driven action.
+
+## Animations / transitions
+
+- **Tile entry**: stagger fade-in (~30 ms per tile) on first render.
+- **Level-up celebration**: when `ach_level_current_id` flips on a
+push (detect via `[getUserProfile](../../api/classes/WSAPIUser.md#getuserprofile)`'s
+`props_change`), animate the newly-reached tile (scale-up,
+shine sweep). The default Smartico UI does this on the header
+badge, not on the level-map tiles.
+
+## Mobile vs desktop
+
+- **Grid columns**: desktop responsive (3–5 columns depending on
+viewport); mobile 2 columns.
+- **Detail view**: desktop opens as a centered modal with backdrop
+dim; mobile opens as a full-screen sheet.
+- **Counter rows in detail**: identical on both — three stacked
+progress bars on Logic 2 labels.
+
+## Performance
+
+- The 30 s cache deduplicates rapid refetches; a poll loop hitting
+`getLevels()` every 5 s effectively translates to one network
+round-trip per 30 s.
+- `getLevels` is suitable to call once at app boot and cache the
+array in your own state (re-fetch only when the user's level
+changes per `props_change`, since the operator-driven ladder
+rarely changes mid-session).
+

package/docs/ui/user/UIGuide_getUserProfile.md

@@ -0,0 +1,213 @@
+# UI Guide — `getUserProfile`
+
+## Overview
+- The synchronous source of truth for the current user's public
+  properties — balances, level, username, avatar, tags, language,
+  inbox count.
+- The SDK keeps a local snapshot updated by a server push channel.
+  Every call returns the latest cached values; no network round-trip.
+- Drive long-lived widgets (header user-bar, balance display, inbox
+  badge, level badge) by **subscribing to `props_change` events** and
+  re-reading via `getUserProfile()` on each fire. Don't poll.
+
+## Subscription pattern
+
+The default Smartico UI registers a single `props_change` listener
+at boot and re-renders the affected widgets from the current
+`getUserProfile()` snapshot. The callback's argument carries only
+the changed keys, so you can branch on which subset of widgets to
+update:
+
+```ts
+window._smartico.on('props_change', (changed) => {
+  const profile = window._smartico.api.getUserProfile();
+
+  if ('ach_points_balance' in changed
+   || 'ach_gems_balance' in changed
+   || 'ach_diamonds_balance' in changed) {
+    console.log('[smartico] balance changed — re-render the currency strip:',
+      profile.ach_points_balance, profile.ach_gems_balance, profile.ach_diamonds_balance);
+  }
+  if ('ach_level_current_id' in changed) {
+    console.log('[smartico] level changed — call getCurrentLevel() and animate the badge');
+  }
+  if ('core_inbox_unread_count' in changed) {
+    console.log('[smartico] inbox count changed — update the inbox badge to:',
+      profile.core_inbox_unread_count);
+  }
+  if ('core_public_tags' in changed) {
+    console.log('[smartico] tags changed — re-evaluate any tag-gated UI:',
+      profile.core_public_tags);
+  }
+});
+```
+
+For one-time reads (e.g. inside a click handler), call
+`getUserProfile()` directly — no subscription needed.
+
+## Balance widget
+
+The default Smartico UI renders a horizontal strip of currency
+counters in the header / menu bar. Render rules:
+
+| Field | Rendered | Format |
+|---|---|---|
+| `ach_points_balance` | Always | Locale-aware integer (e.g. `"1,234"`); show even when zero. |
+| `ach_gems_balance` | Only if the operator has enabled gems for this label | Same locale format. |
+| `ach_diamonds_balance` | Only if the operator has enabled diamonds for this label | Same locale format. |
+
+Gems and diamonds are conditionally rendered per label
+configuration — not just based on whether the value is non-zero. For
+labels that don't use these currencies, hide the counters entirely
+rather than showing `0`. (The SDK doesn't expose label settings; ask
+the operator or detect by other context.)
+
+Pair the counter with an icon for each currency (points icon, gem
+icon, diamond icon). Use brand assets — none ship with the SDK.
+
+## Affordability checks
+
+`getUserProfile()` is the source for paid-mutation gating across
+the SDK. Same pattern for each domain:
+
+| Method | Read balance for | Compare against |
+|---|---|---|
+| [`buyStoreItem`](../../api/classes/WSAPIStore.md#buystoreitem) | `item.purchase_type` (`'points'` / `'gems'` / `'diamonds'`) | `item.discounted_price ?? item.price` |
+| [`joinClan`](../../api/classes/WSAPIClans.md#joinclan) | `clan.entry_fee_currency_type_id` (`0`/`1`/`2`/`3`) | `clan.entry_fee_amount` |
+| [`registerInTournament`](../../api/classes/WSAPITournaments.md#registerintournament) | Whichever of `registration_cost_points` / `_gems` / `_diamonds` is set | The same field |
+
+Disable the CTA when the user's balance is below the cost; show the
+deficit in the disabled state's text.
+
+## Level badge
+
+Render the level badge using `ach_level_current_id` as a lookup key
+into the level ladder fetched separately:
+
+1. Call [`getLevels`](../../api/classes/WSAPIUser.md#getlevels) once
+   at app boot to cache the full ladder.
+2. On `ach_level_current_id` change (via `props_change`), look up the
+   level by ID and render its `name` + `image`.
+3. For the richer "progress to next level" UI, call
+   [`getCurrentLevel`](../../api/classes/WSAPIUser.md#getcurrentlevel)
+   — it adds a computed `progress` percentage.
+
+`ach_level_current_id` may briefly be `0` (or undefined) for new
+users with no points yet. Handle that as "no level" — render a
+default badge (e.g. "Newcomer" or hide the badge).
+
+## Avatar widget
+
+`avatar_url` is a CDN URL resolved by the SDK from the server's
+`avatar_id` field. To render:
+
+- Place inside a square container (1:1 aspect ratio).
+- The default Smartico UI proxies the URL through a CDN resizer
+  (`resize/128/128/webp/...`) for size-appropriate fetches and
+  WebP-where-supported. Brands that don't use that resizer can
+  load `avatar_url` directly.
+- **No built-in placeholder**: when `avatar_url` is missing, the
+  default Smartico UI renders an empty container (no fallback
+  image). Provide your own placeholder asset / initial-letter
+  fallback if the empty state matters.
+
+## Username widget
+
+`public_username` is the user's display name. Fallback chain:
+
+- `public_username` if set
+- `'...'` (three dots) or a localized "Anonymous" string if not set
+
+The default Smartico UI uses `'...'`. There's no automatic fallback
+to `user_ext_id` — that field is internal and should never be
+displayed.
+
+## Inbox badge
+
+`core_inbox_unread_count` is the authoritative source for inbox
+unread badge rendering — it's push-updated in real time (under 1
+second), unlike
+[`getInboxUnreadCount()`](../../api/classes/WSAPIInbox.md#getinboxunreadcount)
+which caches for 30 s.
+
+Render rules:
+
+- `0` (or undefined) → badge hidden entirely
+- `1`–`N` → render the raw integer (e.g. `"5"`, `"42"`)
+- No truncation to `"99+"` in the default Smartico UI; brands that
+  want a cap should apply it themselves.
+
+## Public tags
+
+`core_public_tags` is an array of operator-defined uppercase strings
+(e.g. `['VIP', 'NEWSLETTER_OPT_IN']`). Use them to gate UI
+visibility — show a "VIP rewards" link only when `'VIP'` is in the
+array.
+
+To modify tags, use `_smartico.updatePublicTags(operation, tags)` —
+the change round-trips through the server and arrives back as a
+`props_change` push (usually within ~1 second).
+
+## Language
+
+`core_user_language` is the server-stored language code (e.g.
+`"en"`, `"de"`). The SDK uses this for:
+
+- Pre-translated content fields on missions, bonuses, clans, etc.
+- The `lang_code` parameter that
+  [`getTranslations`](../../api/classes/WSAPIGeneral.md#gettranslations)
+  is typically called with.
+
+When the user just changed language client-side, this field may
+briefly lag the local intent until the server push arrives. If your
+UI needs instant accuracy (e.g. switching the in-page language
+without a refresh), use `_smartico.getPublicProps()` which applies
+the client-side fallback.
+
+## AI-recommended amounts
+
+`core_recommended_deposit_amount` and
+`core_recommended_casino_bet_amount` are AI-computed for the user.
+The default Smartico UI doesn't render them — they're exposed for
+custom integrations (e.g. operator-specific deposit prompts,
+personalized bet suggestions).
+
+Guard against `undefined` — these are absent for users with no
+current recommendation.
+
+## Empty / loading / error states
+
+- **Pre-identify**: `getUserProfile()` throws
+  `"Tracker is not initialized, cannot getUserProfile"`. Render
+  widgets as skeleton/placeholder until the `identify` event fires
+  (or until the first `props_change` callback).
+- **Visitor mode**: not supported; will throw. Render a "Log in to
+  see your profile" CTA instead of a balance widget for anonymous
+  sessions.
+- **Stale data**: real-time push usually keeps the snapshot under 1
+  second behind server state. There's no explicit "stale" state —
+  trust the snapshot.
+
+## Animations / transitions
+
+- **Balance changes**: when `ach_points_balance` / `_gems` /
+  `_diamonds` change, animate the count-up/down between the prior
+  and new value (200–600 ms). Detect by diffing the prior snapshot
+  inside `props_change`.
+- **Level-up**: when `ach_level_current_id` increases, play a
+  celebration animation on the badge (sparkle, scale-up, color
+  flash). Detect by diffing the prior `ach_level_current_id`.
+- **Inbox badge appearing**: when `core_inbox_unread_count` flips
+  from `0` to `>0`, animate the badge fade-in.
+
+## Performance
+
+- `getUserProfile()` is effectively free (synchronous, in-memory
+  copy). Call it as often as you need.
+- Avoid re-rendering every widget on every `props_change` push —
+  branch on the changed keys and re-render only the affected
+  surfaces.
+- `getUserProfile()` returns a shallow copy on each call; for
+  performance-critical paths (e.g. animations), prefer memoizing
+  the result inside `props_change` rather than calling on every
+  frame.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smartico/public-api",
-	"version": "0.0.379",
+	"version": "0.0.381",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -24,7 +24,7 @@
 		"bump-ach": "cd ../tracker/ach && npm install @smartico/public-api@latest --legacy-peer-deps",
 		"bump-bo-server": "cd ../bo_server/server && source ~/.nvm/nvm.sh && nvm use v13.13.0 && npm install @smartico/public-api@latest",
 		"bump-bo-client": "cd ../bo_server/client && source ~/.nvm/nvm.sh && nvm use v13.13.0 && npm install @smartico/public-api@latest",
-		"doc": "typedoc"
+		"doc": "typedoc && node scripts/postdoc-cleanup.js"
 	},
 	"author": "",
 	"license": "ISC",
@@ -40,6 +40,6 @@
 		"typedoc-plugin-markdown": "^4.11.0",
 		"typedoc-plugin-merge-modules": "^7.0.0",
 		"typescript": "~5.1.0",
-		"@types/node": "^18.19.130"
+		"@types/node": "^22.9.0"
 	}
 }