@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/getInboxMessages.md

@@ -0,0 +1,146 @@
+# getInboxMessages — API (TInboxMessage)
+
+> Returns the user's inbox messages — newest first — with optional filtering by category, favorite status, and read state.
+> Import: `import { TInboxMessage } from '@smartico/public-api'`
+> Search terms: getInboxMessages, inbox, TInboxMessage, InboxCategories, onUpdate, subscription, sent_date, message_guid, read, favorite, category_id, expire_on_dt
+
+## Signature
+```ts
+_smartico.api.getInboxMessages({
+		from,
+		to,
+		onlyFavorite,
+		categoryId,
+		read_status,
+		onUpdate,
+	}: {
+		from?: number;
+		to?: number;
+		onlyFavorite?: boolean;
+		categoryId?: InboxCategories;
+		read_status?: InboxReadStatus;
+		onUpdate?: (data: TInboxMessage[]) => void;
+	} = {}): Promise<TInboxMessage[]>
+```
+
+## Parameters
+- `params` — Optional filters + subscription.
+- `params.from` — First message index (0-based). Defaults to `0`.
+- `params.to` — Last message index (exclusive). Defaults to `20`. Server caps the page at 20.
+- `params.onlyFavorite` — When `true`, returns only favorite (starred) messages.
+- `params.categoryId` — When set, returns only messages in this category (`InboxCategories`).
+- `params.read_status` — When set, scopes to read or unread only (`InboxReadStatus`).
+- `params.onUpdate` — Callback invoked with the full refreshed list when a new message arrives.
+
+## Returns — `Promise<TInboxMessage[]>`
+Array of `TInboxMessage`. Each item:
+- `message_guid` (string) — Unique identifier of the message. Pass to `getInboxMessageBody` and the mark / favorite / delete mutations.
+- `sent_date` (string) — Date-time the message was sent, as a `"dd/MM/yyyy HH:mm:ss"` string (server local — NOT ISO-8601, so `new Date(sent_date)` will not parse it).
+- `read` (boolean) — `true` when the message has been marked read.
+- `favorite` (boolean) — `true` when the message has been starred (favorited).
+- `category_id` (InboxCategories) — Operator-assigned category (`InboxCategories`).
+- `expire_on_dt` (number) — Expiry timestamp as Unix-ms epoch. Server filters out expired messages from list responses — consumers rarely see this set unless the expiry is upcoming.
+
+## Behavioral contract
+**Subscription model (`onUpdate`)**
+The callback receives the FULL refreshed message list (never a
+diff/patch). Each subsequent call to `getInboxMessages({ onUpdate })`
+REPLACES the prior callback. Pass `onUpdate: undefined` (or omit
+it) to keep the prior callback in place; the callback is never
+auto-cleared.
+
+**Update triggers** — the callback fires ONLY when:
+
+1. A new message is pushed by the server (campaign / automation /
+ operator send). The refreshed list includes the new message
+ at the top.
+
+Does NOT fire for: `markInboxMessageAsRead`,
+`markAllInboxMessagesAsRead`,
+`markUnmarkInboxMessageAsFavorite`, `deleteInboxMessage`,
+`deleteAllInboxMessages`. After a mutation, re-call
+`getInboxMessages` manually if your UI needs the refreshed list
+— or maintain optimistic state locally.
+
+**Pagination**
+`from` (defaults to `0`) and `to` (defaults to `20`) define a
+half-open range of message indices. The server caps the page at
+**20 messages per request** — passing `to - from > 20` silently
+truncates to 20. For "load more" pagination, advance `from` by
+the prior page size on each subsequent call.
+
+**Filters**
+All filters are ANDed server-side. Omitting a filter means "no
+constraint" on that dimension:
+- `categoryId` (`InboxCategories`): `General` (0),
+ `Platform` (1), `Personal` (2). Omit to get all categories.
+- `onlyFavorite: true` returns only starred messages.
+ Omit / `false` returns all (starred and not).
+- `read_status` (`InboxReadStatus`): `UnreadOnly` (1) or
+ `ReadOnly` (2). Omit to get both.
+
+**Server-side filtering** (always applied)
+Expired messages (`expire_on_dt` in the past) and
+soft-deleted messages are excluded server-side. Consumers do not
+need to filter for these.
+
+**No client cache**: every call sends a fresh server round-trip.
+To avoid redundant fetches in your UI, hold the result in
+application state and re-fetch on `onUpdate` fires or explicit
+user-driven refresh.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getInboxMessages`](../../docs/ui/inbox/UIGuide_getInboxMessages.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const messages = await window._smartico.api.getInboxMessages({
+  onUpdate: (refreshed) => {
+    console.log('[smartico] new inbox message arrived — re-render the list from this array, new message is at index 0:', refreshed);
+  },
+});
+
+// For each message, fetch its body for the list view (title, preview, icon).
+for (const msg of messages) {
+  const body = await window._smartico.api.getInboxMessageBody(msg.message_guid);
+  console.log('[smartico] render message', msg.message_guid,
+    '— title:', body.title,
+    '— preview:', body.preview_body,
+    '— read:', msg.read,
+    '— favorite:', msg.favorite);
+}
+
+// "Load more" pagination — advance from by the prior page size.
+const page2 = await window._smartico.api.getInboxMessages({ from: 20, to: 40 });
+console.log('[smartico] page 2:', page2.length, 'messages');
+
+// Filter examples.
+const onlyStarred = await window._smartico.api.getInboxMessages({ onlyFavorite: true });
+const onlyUnread = await window._smartico.api.getInboxMessages({ read_status: 1 });  // InboxReadStatus.UnreadOnly
+```
+
+### 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
+[
+  {
+    "sent_date": "24/06/2026 07:43:31",
+    "message_guid": "00000000-0000-0000-0000-000000000000",
+    "read": true,
+    "favorite": false,
+    "category_id": 0,
+    "expire_on_dt": 1784879011491
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getInboxMessageBody`
+- `InboxCategories`
+- `InboxReadStatus`

package/docs/capabilities/getInboxUnreadCount.md

@@ -0,0 +1,54 @@
+# getInboxUnreadCount — API
+
+> Returns the user's current unread inbox message count — a single integer suitable for driving a header badge.
+> Import: `import { /* types */ } from '@smartico/public-api'`
+> Search terms: getInboxUnreadCount, inbox, onUpdate, subscription
+
+## Signature
+```ts
+_smartico.api.getInboxUnreadCount({ onUpdate }: { onUpdate?: (unread_count: number) => void } = {}): Promise<number>
+```
+
+## Parameters
+- `params` — Optional subscription bag.
+- `params.onUpdate` — Callback invoked with the new unread count whenever it changes (push-driven).
+
+## Returns
+Resolves to `number`.
+
+## Behavioral contract
+**Subscription model**
+`onUpdate` fires whenever the cached value changes — either on a
+push from the user-properties channel (new message arrival,
+mark-as-read, delete) or after an inbox-list fetch that returns
+a fresh count.
+
+**Cache TTL**: 30 seconds. The cached value is patched in place
+by push events (no full re-fetch on every push), so the
+`onUpdate` callback reflects server state with sub-second latency
+regardless of the TTL.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+// Static read for an initial badge render.
+const count = await window._smartico.api.getInboxUnreadCount();
+console.log('[smartico] inbox badge initial count:', count);
+
+// Live subscription for badge updates.
+await window._smartico.api.getInboxUnreadCount({
+  onUpdate: (newCount) => {
+    console.log('[smartico] inbox count changed — update the badge to:', newCount,
+      '— hide badge entirely when 0, show raw integer otherwise (no "99+" cap in the default UI)');
+  },
+});
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getUserProfile`

package/docs/capabilities/getJackpotEligibleGames.md

@@ -0,0 +1,93 @@
+# getJackpotEligibleGames — API (TGetJackpotEligibleGamesResponse)
+
+> Returns the casino games eligible to contribute to a specific jackpot — the catalog the user must play to grow the pot.
+> Import: `import { TGetJackpotEligibleGamesResponse } from '@smartico/public-api'`
+> Search terms: getJackpotEligibleGames, jackpots, TGetJackpotEligibleGamesResponse, JackpotEligibleGame, onUpdate, subscription, eligible_games
+
+## Signature
+```ts
+_smartico.api.getJackpotEligibleGames({ jp_template_id, onUpdate } : {
+		/** Jackpot template ID (required). */
+		jp_template_id: number,
+		/** Optional callback; not auto-invoked today. */
+		onUpdate?: () => void,
+	}): Promise<TGetJackpotEligibleGamesResponse>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TGetJackpotEligibleGamesResponse>`
+`TGetJackpotEligibleGamesResponse`:
+- `eligible_games` (JackpotEligibleGame[])
+  - `game_id` (number) — ID of the game on Smartico side
+  - `ext_game_id` (string) — ID of the game on operator side
+  - `name` (string) — Name of the game
+  - `link` (string) — Link to the game
+  - `image` (string) — Image of the game
+  - `enabled` (boolean) — Whether the game is enabled
+  - `game_categories` (string[]) — Categories of the game
+  - `game_provider` (string) — Provider of the game
+  - `mobile_spec_link` (string) — The link to the mobile game
+  - `priority` (number) — The priority of the game
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode not supported.
+- `jp_template_id` is mandatory.
+
+**`onUpdate` caveat**
+The `onUpdate` callback is accepted to match the SDK's subscription
+contract but is NOT auto-invoked by any current server push. It will only
+fire if a consumer (or a future SDK version) explicitly pushes an update.
+Treat it as a no-op for now.
+
+**Refresh**
+- The SDK caches per `jp_template_id` for 30 seconds.
+- Cache does NOT clear on opt-in / opt-out / jackpot-win — eligible-game
+  lists rarely change during a session. Wait for the 30 s TTL.
+
+**Error handling**
+Non-zero `errCode` on control-group users or generic server errors.
+Branch on `errCode === 0` and surface `errMsg` on failure.
+
+**Visitor mode**: not supported.
+
+**UI guidance**: see [UI Guide — `getJackpotEligibleGames`](../../docs/ui/jackpots/UIGuide_getJackpotEligibleGames.md).
+
+## Example
+```ts
+const [jp] = await window._smartico.api.jackpotGet({ jp_template_id: 42 });
+
+if (jp?.ach_related_game_allow_all) {
+    console.log('[smartico] all games eligible — hide the eligible-games tab');
+    return;
+}
+
+const r = await window._smartico.api.getJackpotEligibleGames({ jp_template_id: 42 });
+console.log('[smartico] render', r.eligible_games.length, 'eligible game tiles');
+```
+
+### 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
+{
+  "eligible_games": [
+    {
+      "game_id": 2106041136,
+      "ext_game_id": "666",
+      "name": "Deadman's Luck",
+      "image": "https://cdn.example/d67393a1c13d95219e6d03-SlotLogowithSkulls.png",
+      "enabled": true,
+      "priority": 1
+    }
+  ]
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `JackpotDetails.ach_related_game_allow_all`
+- `TGetJackpotEligibleGamesResponse`

package/docs/capabilities/getJackpotWinners.md

@@ -0,0 +1,113 @@
+# getJackpotWinners — API (JackpotWinnerHistory)
+
+> Returns past winners of a specific jackpot template, paginated.
+> Import: `import { JackpotWinnerHistory } from '@smartico/public-api'`
+> Search terms: getJackpotWinners, jackpots, JackpotWinnerHistory, JackPotWinner, winner, win_date_ts, jp_pot_id
+
+## Signature
+```ts
+_smartico.api.getJackpotWinners({
+		limit,
+		offset,
+		jp_template_id,
+	}: {
+		/** Page size (default 20). */
+		limit?: number;
+		/** Pagination offset (default 0). */
+		offset?: number;
+		/** Jackpot template ID (required). */
+		jp_template_id?: number;
+	}): Promise<JackpotWinnerHistory[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<JackpotWinnerHistory[]>`
+Array of `JackpotWinnerHistory`. Each item:
+- `jp_pot_id` (number) — Id of the jackpot pot
+- `win_date_ts` (number) — Date of winning in milliseconds
+- `winner` (JackPotWinner) — Info about jackpot winner
+  - `is_me` (boolean) — Flag indicating that this winner is the currently logged in user
+  - `public_username` (string) — Name of the winner, note that for all users except is_me, the name is masked by default, but masking can be disabled by request to Smartico AM team
+  - `winning_amount_jp_currency` (number) — Won amount in the Jackpot currency
+  - `winning_amount_wallet_currency` (number) — Won amount in the user Wallet currency
+  - `winning_position` (number) — Position of the winner. Relevant for jackpots where there could be multiple winners
+  - `avatar_id` (string) — Avatar of the winner
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode not supported.
+- `jp_template_id` is mandatory — the SDK throws synchronously if missing.
+- The consumer SHOULD check
+ `JackpotDetails.expose_winners_over_api` before calling, since
+ the server does not enforce it.
+
+**Pagination**
+Server default page size is 20. Pass `limit` and `offset` to paginate
+(e.g. infinite-scroll). The wire response carries a `has_more` flag, but
+this SDK method returns only the `winners` array — detect end-of-list by
+a returned array shorter than `limit`.
+
+**Currency caveat**
+Winner amounts in the response (`winner.winning_amount_jp_currency`) are
+in the jackpot's NATIVE currency, NOT the user's wallet currency. If a
+user-currency display is needed, the consumer must convert client-side.
+
+**Refresh**
+- The SDK caches per `jp_template_id` for 30 seconds.
+- Caches clear on jackpot-win push events and on opt-in / opt-out.
+
+**Error handling**
+Non-zero `errCode` on control-group users or generic server errors. The
+SDK does NOT enumerate distinct codes — branch on `errCode === 0` and
+surface `errMsg` on failure.
+
+**Visitor mode**: not supported.
+
+**UI guidance**: see [UI Guide — `getJackpotWinners`](../../docs/ui/jackpots/UIGuide_getJackpotWinners.md).
+
+## Example
+```ts
+const [jp] = await window._smartico.api.jackpotGet({ jp_template_id: 42 });
+
+if (!jp || !jp.expose_winners_over_api) {
+    console.log('[smartico] winners hidden by operator config — hide the winners tab');
+    return;
+}
+
+const winners = await window._smartico.api.getJackpotWinners({
+    jp_template_id: 42,
+    limit:          20,
+    offset:         0,
+});
+console.log('[smartico] render', winners.length, 'recent winner rows (amounts in', jp.jp_currency + ')');
+```
+
+### 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
+[
+  {
+    "winner": {
+      "is_me": false,
+      "public_username": "731:*****",
+      "winning_amount_jp_currency": 16.720332488,
+      "winning_amount_wallet_currency": 98.525768722,
+      "winning_position": 1,
+      "avatar_id": "183751796",
+      "avatar_real_id": null
+    },
+    "win_date_ts": 1782295329703,
+    "jp_pot_id": 306053
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `JackpotDetails`
+- `JackpotDetails.expose_winners_over_api`
+- `JackpotWinnerHistory`

package/docs/capabilities/getLeaderBoard.md

@@ -0,0 +1,187 @@
+# getLeaderBoard — API (LeaderBoardDetailsT)
+
+> Returns the operator-configured standalone leaderboard for the given period type — top-20 ranked entries, the current user's own entry (when authenticated), and the configured prize table.
+> Import: `import { LeaderBoardDetailsT } from '@smartico/public-api'`
+> Search terms: getLeaderBoard, leaderboard, getLeaderboard, LeaderBoardDetailsT, LeaderBoardPeriodType, LeaderBoardsRewardsT, LeaderBoardUserT, board_id, name, description, rules, period_type_id, version_id, create_date, rewards
+
+## Signature
+```ts
+_smartico.api.getLeaderBoard(periodType: LeaderBoardPeriodType, getPreviousPeriod?: boolean | number): Promise<LeaderBoardDetailsT>
+```
+
+## Parameters
+- `periodType` — The board's period type (`LeaderBoardPeriodType`). Selects which pre-configured board to fetch; the board itself is bound to one period by the operator.
+- `getPreviousPeriod` — Which period to fetch. `false` (default) = current in-progress period; `true` = the most recent finalized snapshot; a number `n` = the n-th previous snapshot (`1` = previous, `2` = the one before, …).
+
+## Returns — `Promise<LeaderBoardDetailsT>`
+`LeaderBoardDetailsT`:
+- `board_id` (number) — Stable ID of the leaderboard.
+- `name` (string) — Operator-defined display name.
+- `description` (string) — Operator-defined description (HTML allowed).
+- `rules` (string) — Operator-defined rules / terms (HTML allowed).
+- `period_type_id` (LeaderBoardPeriodType) — Period type this board is bound to (`LeaderBoardPeriodType`).
+- `version_id` (number) — Snapshot version. `0` for the live current period; a positive value identifies a finalized previous-period snapshot (see `getPreviousPeriod`).
+- `create_date` (number) — Snapshot creation timestamp (Unix ms). `0` for the live current period; the finalization time for a previous-period snapshot.
+- `rewards` (LeaderBoardsRewardsT[]) — Per-place prize table; the array length is the number of paid places.
+  - `place` (number) — Place number (1-based).
+  - `points` (number) — Gamification points awarded to the user occupying this place at period finalization.
+- `users` (LeaderBoardUserT[]) — Top-20 ranked entries (server-capped), sorted by `position` ASC. Empty when fetched via `getLeaderBoards()` (metadata-only list).
+  - `public_username` (string) — Display username (operator-defined alias).
+  - `avatar_url` (string) — Resolved CDN URL for the participant's avatar. May be empty when the participant has no custom avatar — fall back to a level-based default using `level_id`.
+  - `level_id` (number) — The participant's level id — use it to resolve a level-based default avatar when `avatar_url` is empty.
+  - `position` (number) — Rank in the leaderboard (DENSE_RANK over all participants). `-1` on the `me` entry signals "unranked / outside the window".
+  - `points` (number) — Participant's points for this period.
+  - `is_me` (boolean) — `true` when this row is the current authenticated user. Always `true` on the `me` entry.
+- `me` (LeaderBoardUserT) — Current user's own entry. `undefined` for visitor sessions. For authenticated users, `position === -1` means the user is unranked / outside the ranked window.
+  - `public_username` (string) — Display username (operator-defined alias).
+  - `avatar_url` (string) — Resolved CDN URL for the participant's avatar. May be empty when the participant has no custom avatar — fall back to a level-based default using `level_id`.
+  - `level_id` (number) — The participant's level id — use it to resolve a level-based default avatar when `avatar_url` is empty.
+  - `position` (number) — Rank in the leaderboard (DENSE_RANK over all participants). `-1` on the `me` entry signals "unranked / outside the window".
+  - `points` (number) — Participant's points for this period.
+  - `is_me` (boolean) — `true` when this row is the current authenticated user. Always `true` on the `me` entry.
+
+## Behavioral contract
+**Return value note** — the runtime may return `undefined` if no
+board is configured for the requested `periodType`, despite the
+static return type being `Promise<LeaderBoardDetailsT>`. Defend
+against that case in consumer code.
+
+**Preconditions**
+Pass a `periodType` from `LeaderBoardPeriodType`(`DAILY = 1`, `WEEKLY = 2`, `MONTHLY = 3`). Pass
+`getPreviousPeriod: true` to fetch the most-recently-ended
+period's snapshot (yesterday's / last week's / last month's
+results) instead of the current live period. To reach older
+snapshots, pass a number instead of a boolean: `1` = previous
+period, `2` = the one before that, and so on (`0` / `false` =
+current). Use the snapshot's `create_date` / `version_id` to label
+which historical run a previous-period board is. How far back
+snapshots are retained is operator-configured.
+
+**Top-20 cap**
+The server hard-caps `users[]` at 20 entries, ordered by
+`position` ASC. Position values are server-computed (DENSE_RANK
+over all participants); the truncation at 20 is for transport
+size only — `position` may exceed 20 elsewhere.
+
+**The `me` field**
+Always populated for authenticated users (even when they have
+zero points in the period). `me.position === -1` is the signal
+that the user is active but ranked outside the top 20 (or has no
+activity yet). `me` is `undefined` for visitor-mode sessions.
+
+**Rewards are points only**
+`rewards[].points` are gamification points credited to the user's
+balance when the period finalizes. The leaderboard never awards
+gems, diamonds, store items, or bonuses. The first element of
+the array is the prize for place 1, the second for place 2, and
+so on. The array length is the number of paid places.
+
+**Cache TTL**
+The SDK caches each response for 30 seconds. 
+
+**Period boundaries**
+The server finalizes each period on a server-configurable
+schedule: DAILY at midnight + operator-defined offset; WEEKLY
+at the start of Monday; MONTHLY on the 1st of each month. At
+finalization, the server distributes the configured `rewards[]`
+points to the top placeholders and resets the live board. After
+finalization, `getLeaderBoard(periodType, false)` returns the
+NEW (empty) period's board; call with
+`getPreviousPeriod: true` to see the just-ended standings.
+
+**Refresh model**
+- One-shot fetch (no subscription).
+- No push event refreshes the cache; finalization at the period
+ boundary is NOT pushed to the client.
+- Poll manually if the consumer needs near-live state during an
+ in-progress period.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getLeaderBoard`](../../docs/ui/leaderboard/UIGuide_getLeaderBoard.md).
+
+**Visitor mode**: supported. The same shape is returned, scoped
+to the brand's public leaderboard. `me` is `undefined` for
+visitors.
+
+## Example
+```ts
+import { LeaderBoardPeriodType } from '@smartico/public-api';
+
+const board = await window._smartico.api.getLeaderBoard(LeaderBoardPeriodType.WEEKLY);
+
+if (!board) {
+  console.log('[smartico] no weekly board configured for this label — hide the leaderboard surface');
+  return;
+}
+
+console.log('[smartico] render leaderboard tab —', board.name, '—', board.users.length, 'ranked entries (top 20 max)');
+
+// Render prize table.
+for (const reward of board.rewards) {
+  console.log('[smartico] prize row — place', reward.place, '→', reward.points, 'points');
+}
+
+// "Me" panel — sticky row showing the current user's rank.
+if (board.me) {
+  if (board.me.position === -1) {
+    console.log('[smartico] user is unranked — show "You are unranked, earn points to enter the leaderboard"');
+  } else if (board.me.position > 20) {
+    console.log('[smartico] user is ranked', board.me.position, 'but outside the visible top-20 — show sticky "me" row with', board.me.points, 'points');
+  } else {
+    console.log('[smartico] user is in the top 20 at position', board.me.position, '— highlight their row in the main list');
+  }
+}
+
+// Switch to previous period view — cached separately from the current period.
+const prev = await window._smartico.api.getLeaderBoard(LeaderBoardPeriodType.WEEKLY, true);
+console.log('[smartico] previous-week standings — render with greyed-out "ended" treatment:', prev?.users.length, 'finalists');
+
+// Visitor-mode equivalent — me is always undefined.
+// const visitorBoard = await window._smartico.vapi('EN').getLeaderBoard(LeaderBoardPeriodType.DAILY);
+```
+
+### 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
+{
+  "board_id": 143,
+  "name": "Daily Leaderboard",
+  "description": "This <b>Leaderboard</b> is showing the names and current scores of the leading competitors of the day.<br>\nYou can put any text here to describe this Leaderb…",
+  "rules": "Leaderboards are the simplest form of tournaments. Easy to set up in 5 minutes or less. Boards only calculate gamification point progress, and award points f…",
+  "period_type_id": 1,
+  "version_id": 0,
+  "create_date": 0,
+  "rewards": [
+    {
+      "place": 1,
+      "points": 100
+    }
+  ],
+  "users": [
+    {
+      "public_username": "Matt*****",
+      "avatar_url": "https://cdn.example/avatar/344499363",
+      "level_id": 700,
+      "position": 1,
+      "points": 2155,
+      "is_me": false
+    }
+  ],
+  "me": {
+    "public_username": "Antonio",
+    "avatar_url": "https://cdn.example/avatars/12/00000000-0000-0000-0000-000000000000.png",
+    "level_id": 698,
+    "position": -1,
+    "points": 0,
+    "is_me": true
+  }
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getLeaderBoards`
+- `LeaderBoardPeriodType`

package/docs/capabilities/getLeaderBoards.md

@@ -0,0 +1,88 @@
+# getLeaderBoards — API (LeaderBoardDetailsT)
+
+> Returns the list of leaderboards the operator has configured for this label — **metadata only, without participants**.
+> Import: `import { LeaderBoardDetailsT } from '@smartico/public-api'`
+> Search terms: getLeaderBoards, leaderboard, getLeaderboards, LeaderBoardDetailsT, LeaderBoardPeriodType, LeaderBoardsRewardsT, LeaderBoardUserT
+
+## Signature
+```ts
+_smartico.api.getLeaderBoards(): Promise<LeaderBoardDetailsT[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<LeaderBoardDetailsT[]>`
+Array of `LeaderBoardDetailsT`. Each item:
+- `board_id` (number) — Stable ID of the leaderboard.
+- `name` (string) — Operator-defined display name.
+- `description` (string) — Operator-defined description (HTML allowed).
+- `rules` (string) — Operator-defined rules / terms (HTML allowed).
+- `period_type_id` (LeaderBoardPeriodType) — Period type this board is bound to (`LeaderBoardPeriodType`).
+- `version_id` (number) — Snapshot version. `0` for the live current period; a positive value identifies a finalized previous-period snapshot (see `getPreviousPeriod`).
+- `create_date` (number) — Snapshot creation timestamp (Unix ms). `0` for the live current period; the finalization time for a previous-period snapshot.
+- `rewards` (LeaderBoardsRewardsT[]) — Per-place prize table; the array length is the number of paid places.
+  - `place` (number) — Place number (1-based).
+  - `points` (number) — Gamification points awarded to the user occupying this place at period finalization.
+- `users` (LeaderBoardUserT[]) — Top-20 ranked entries (server-capped), sorted by `position` ASC. Empty when fetched via `getLeaderBoards()` (metadata-only list).
+  - `public_username` (string) — Display username (operator-defined alias).
+  - `avatar_url` (string) — Resolved CDN URL for the participant's avatar. May be empty when the participant has no custom avatar — fall back to a level-based default using `level_id`.
+  - `level_id` (number) — The participant's level id — use it to resolve a level-based default avatar when `avatar_url` is empty.
+  - `position` (number) — Rank in the leaderboard (DENSE_RANK over all participants). `-1` on the `me` entry signals "unranked / outside the window".
+  - `points` (number) — Participant's points for this period.
+  - `is_me` (boolean) — `true` when this row is the current authenticated user. Always `true` on the `me` entry.
+- `me` (LeaderBoardUserT) — Current user's own entry. `undefined` for visitor sessions. For authenticated users, `position === -1` means the user is unranked / outside the ranked window.
+  - `public_username` (string) — Display username (operator-defined alias).
+  - `avatar_url` (string) — Resolved CDN URL for the participant's avatar. May be empty when the participant has no custom avatar — fall back to a level-based default using `level_id`.
+  - `level_id` (number) — The participant's level id — use it to resolve a level-based default avatar when `avatar_url` is empty.
+  - `position` (number) — Rank in the leaderboard (DENSE_RANK over all participants). `-1` on the `me` entry signals "unranked / outside the window".
+  - `points` (number) — Participant's points for this period.
+  - `is_me` (boolean) — `true` when this row is the current authenticated user. Always `true` on the `me` entry.
+
+## Behavioral contract
+**Returned shape**
+An array of `LeaderBoardDetailsT`, one per configured board, ordered by
+`period_type_id` ascending (DAILY, WEEKLY, MONTHLY, …). On every entry
+`users` is an empty array and `me` is `undefined` — this call never
+carries participant data. Read `period_type_id` from each entry and pass
+it to `getLeaderBoard` to load that board's standings.
+
+**Empty result**
+Resolves to an empty array when the label has no leaderboards configured
+— treat that as "hide the leaderboard surface".
+
+**Cache TTL**
+Cached for 30 seconds under a dedicated key (independent of
+`getLeaderBoard`'s per-period cache). Repeated calls within the
+window return the cached list without a round-trip.
+
+**Refresh model**: one-shot fetch — no subscription, no push. Board
+configuration changes surface on the next cache miss.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**Visitor mode**: supported. Returns the brand's public board list.
+
+## Example
+```ts
+const boards = await window._smartico.api.getLeaderBoards();
+
+if (boards.length === 0) {
+  console.log('[smartico] no leaderboards configured — hide the leaderboard surface');
+  return;
+}
+
+// Render one tab per board from the lightweight list (no players yet).
+console.log('[smartico] render leaderboard tabs:', boards.map(b => b.name));
+
+// When the user opens a tab, load that board's standings on demand.
+const first = boards[0];
+const full = await window._smartico.api.getLeaderBoard(first.period_type_id);
+console.log('[smartico] loaded standings for', first.name, '—', full?.users.length ?? 0, 'players');
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getLeaderBoard`