@smartico/public-api 0.0.387 → 0.0.389

package/docs/api/classes/WSAPILeaderBoard.md

@@ -13,7 +13,9 @@ monthly tabs.
 
 The leaderboard for each period type is configured separately by
 the operator. A label may have any combination of DAILY, WEEKLY,
-and MONTHLY boards configured (or none).
+and MONTHLY boards configured (or none). To discover which boards
+exist before loading any standings, call [getLeaderBoards](#getleaderboards)
+(metadata only) and drive the tab selector from its `period_type_id`s.
 
 #### Parameters
 
@@ -29,12 +31,13 @@ The board's period type
 
 ##### getPreviousPeriod?
 
-`boolean`
+`number` \| `boolean`
 
-When `true`, returns the most recent
-                          finalized snapshot for that period type
-                          (e.g. last week's results). Defaults to
-                          `false` (current in-progress period).
+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
 
@@ -56,10 +59,13 @@ against that case in consumer code.
 Pass a `periodType` from [LeaderBoardPeriodType](../enumerations/LeaderBoardPeriodType.md)
 (`DAILY = 1`, `WEEKLY = 2`, `MONTHLY = 3`). Pass
 `getPreviousPeriod: true` to fetch the most-recently-ended
-period's snapshot (yesterday's results, last week's results,
-last month's results) instead of the current live period. The
-SDK only exposes one period back — older snapshots are not
-reachable through this method.
+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
@@ -147,3 +153,73 @@ console.log('[smartico] previous-week standings — render with greyed-out "ende
 ```
 
 ***
+
+### getLeaderBoards()
+
+> **getLeaderBoards**(): `Promise`\<[`LeaderBoardDetailsT`](../interfaces/LeaderBoardDetailsT.md)[]\>
+
+Returns the list of leaderboards the operator has configured for this
+label — **metadata only, without participants**. Use it to discover
+which boards exist (and their period types) so you can render the
+board/tab selector, then load a specific board's standings on demand
+with [getLeaderBoard](#getleaderboard).
+
+This is the lightweight discovery counterpart to [getLeaderBoard](#getleaderboard):
+it issues one round-trip that returns every board's identity, name,
+description, rules, `period_type_id`, and prize table, but **not** the
+ranked players. Fetching the full standings for one board (the top-20
+`users[]` and the caller's own `me` entry) is what [getLeaderBoard](#getleaderboard)
+does per period.
+
+#### Returns
+
+`Promise`\<[`LeaderBoardDetailsT`](../interfaces/LeaderBoardDetailsT.md)[]\>
+
+Promise resolving to the array of configured boards
+         (metadata only). Empty array when none are configured.
+
+#### Remarks
+
+**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](#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](#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');
+```
+
+***

package/docs/api/interfaces/LeaderBoardDetailsT.md

@@ -46,6 +46,24 @@ Period type this board is bound to ([LeaderBoardPeriodType](../enumerations/Lead
 
 ***
 
+### version\_id
+
+> **version\_id**: `number`
+
+Snapshot version. `0` for the live current period; a positive value
+identifies a finalized previous-period snapshot (see `getPreviousPeriod`).
+
+***
+
+### create\_date
+
+> **create\_date**: `number`
+
+Snapshot creation timestamp (Unix ms). `0` for the live current period;
+the finalization time for a previous-period snapshot.
+
+***
+
 ### rewards
 
 > **rewards**: [`LeaderBoardsRewardsT`](LeaderBoardsRewardsT.md)[]
@@ -59,6 +77,7 @@ Per-place prize table; the array length is the number of paid places.
 > **users**: [`LeaderBoardUserT`](LeaderBoardUserT.md)[]
 
 Top-20 ranked entries (server-capped), sorted by `position` ASC.
+Empty when fetched via `getLeaderBoards()` (metadata-only list).
 
 ***
 

package/docs/api/interfaces/LeaderBoardUserT.md

@@ -16,7 +16,18 @@ Display username (operator-defined alias).
 
 > **avatar\_url**: `string`
 
-Resolved CDN URL for the participant's avatar.
+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
+
+> **level\_id**: `number`
+
+The participant's level id — use it to resolve a level-based default
+avatar when `avatar_url` is empty.
 
 ***
 
@@ -41,4 +52,5 @@ Participant's points for this period.
 
 > **is\_me**: `boolean`
 
-`true` when this row is the current authenticated user.
+`true` when this row is the current authenticated user. Always `true`
+on the `me` entry.

package/docs/native/PROTOCOL.md

@@ -1872,7 +1872,8 @@ No method-specific fields. Send only the common fields (see [Common Message Fiel
 
 ### getLeaderBoard
 
-Get leaderboard for a specific period type.
+Get one period's leaderboard with its ranked players, or the list of all
+configured boards without players.
 
 #### Request
 
@@ -1880,9 +1881,14 @@ Get leaderboard for a specific period type.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `period_type_id` | `number` | Period type: `1` = Daily, `2` = Weekly, `3` = Monthly (optional, if not set returns all boards) |
+| `period_type_id` | `number` | Period type: `1` = Daily, `2` = Weekly, `3` = Monthly. Optional — if omitted, the response `map` contains **every** configured board. |
 | `snapshot_offset` | `number` | `0` = current period, `1` = previous period, `2` = period before previous, etc. |
-| `include_users` | `boolean` | Whether to include user details (optional) |
+| `include_users` | `boolean` | `true` → each board includes its `positions` (and `userPosition`). `false` (or omitted) → board metadata only, no players — the lightweight "list available boards" mode. |
+
+> **Two modes from one request.** Send `period_type_id` + `include_users: true`
+> to load a single board's standings. Omit `period_type_id` and send
+> `include_users: false` to enumerate all configured boards (metadata only) —
+> useful to build the board/tab selector before loading any standings.
 
 #### Response
 
@@ -1890,9 +1896,31 @@ Get leaderboard for a specific period type.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `leaders` | [`LeaderBoardUserT[]`](../api/interfaces/LeaderBoardUserT.md) | Array of leaderboard entries |
-| `user_position` | `number` | Current user's position |
-| `user_points` | `number` | Current user's points |
+| `map` | `object` | Keyed by `period_type_id` (as a string: `"1"` / `"2"` / `"3"`), one entry per board. With `period_type_id` set in the request only that key is present; omitted → every configured board. |
+
+Each value of `map` is a leaderboard object:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `board_id` | `number` | Stable board id |
+| `period_type_id` | `number` | `1` = Daily, `2` = Weekly, `3` = Monthly |
+| `create_date` | `number` | `0` for the current period; the snapshot timestamp for a previous period |
+| `versiod_id` | `number` | Snapshot version; `0` for the current period (the field is spelled `versiod_id` on the wire) |
+| `reward_points` | `number[]` | Per-place prize points; index `0` = place 1 |
+| `board_public_meta` | `object` | `{ name, description, rules }` display strings (HTML allowed in `description` / `rules`) |
+| `positions` | `LeaderBoardPosition[]` | Ranked entries, top 20, ordered by rank. **Absent when `include_users` is `false`.** |
+| `userPosition` | `LeaderBoardPosition` | The requesting user's own entry. Absent when `include_users` is `false`, or when the user is unranked. |
+
+Each `LeaderBoardPosition`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `position_in_board` | `number` | Rank (DENSE_RANK); `-1` on `userPosition` = unranked / outside the window |
+| `points_accumulated` | `number` | Participant's points for the period |
+| `public_username` | `string` | Display name (falls back to `user_alt_name`) |
+| `is_me` | `boolean` | `true` for the requesting user's row inside `positions` |
+| `avatar_id` | `string` | Raw avatar id — build the image URL client-side |
+| `level_id` | `number` | The participant's level (factor it into avatar resolution to match the default Smartico UI) |
 
 ---
 

package/docs/ui/leaderboard/UIGuide_getLeaderBoard.md

@@ -9,6 +9,15 @@
 - No subscription, no push refresh. Poll manually if the consumer
   needs live updates during an in-progress period.
 
+## Discovering boards (`getLeaderBoards`)
+Before loading any standings, call `getLeaderBoards()` to discover which
+boards the operator configured (DAILY / WEEKLY / MONTHLY, or none). It
+returns the board list as **metadata only** — `name`, `period_type_id`,
+`rewards`, etc., with `users` empty and `me` undefined — in one lightweight
+round-trip. Build the board/tab selector from that list, then call
+`getLeaderBoard(period_type_id)` to load a tab's standings on demand. If it
+returns an empty array, hide the leaderboard surface entirely.
+
 ## List view organization
 
 The default Smartico UI renders the leaderboard with three top-level
@@ -113,6 +122,12 @@ a fresh fetch within the TTL (e.g. a manual refresh button), call
 `clearCaches()` first — it clears the whole SDK cache, not just this
 board.
 
+To page back through **older** snapshots (not just the immediately
+previous one), pass a number instead of a boolean: `getLeaderBoard(periodType, 2)`
+fetches the period before last, `3` the one before that, etc. Label each
+historical board with its `create_date` / `version_id` so the user knows
+which run they're viewing.
+
 ## Status-specific visual treatments
 
 - **Current period**: full-color rendering; live point counts.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smartico/public-api",
-	"version": "0.0.387",
+	"version": "0.0.389",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/src/CustomSections/AchCustomSection.ts

@@ -48,4 +48,5 @@ export enum LiquidEntityData {
 	Tournament = 10,
 	Raffles = 11,
 	SingleRaffle = 12,
+	Clans = 13,
 }

package/src/Leaderboard/LeaderBoards.ts

@@ -13,19 +13,16 @@ const pointsRewardTransform = (reward_points: number[]): LeaderBoardsRewardsT[]
 
 const getLeaderBoardPlayerTransformed = (user: LeaderBoardPosition, isMe?: boolean): LeaderBoardUserT => {
 	if (user) {
-		const x: LeaderBoardUserT = {
+		return {
 			public_username: user?.public_username || user.user_alt_name,
 			avatar_url: user.avatar_url,
+			level_id: user.level_id,
 			position: user.position_in_board,
 			points: user.points_accumulated,
-			is_me: user.is_me,
+			// The `me` entry is the current user by definition, so force `true`
+			// there; list rows carry the server-provided flag.
+			is_me: isMe ? true : user.is_me,
 		};
-
-		if (isMe) {
-			delete x.is_me;
-		}
-
-		return x;
 	}
 
 	return null;
@@ -33,18 +30,18 @@ const getLeaderBoardPlayerTransformed = (user: LeaderBoardPosition, isMe?: boole
 
 export const getLeaderBoardTransform = (board: LeaderBoardDetails): LeaderBoardDetailsT => {
 	if (board) {
-		const x: LeaderBoardDetailsT = {
+		return {
 			board_id: board.board_id,
 			name: board.board_public_meta.name,
 			description: board.board_public_meta.description,
 			rules: board.board_public_meta.rules,
 			period_type_id: board.period_type_id,
+			version_id: board.versiod_id,
+			create_date: board.create_date,
 			rewards: pointsRewardTransform(board.reward_points),
-			users: board.positions.map((p) => getLeaderBoardPlayerTransformed(p)),
+			users: (board.positions || []).map((p) => getLeaderBoardPlayerTransformed(p)),
 			me: getLeaderBoardPlayerTransformed(board.userPosition, true),
 		};
-
-		return x;
 	}
 
 	return null;

package/src/SmarticoAPI.ts

@@ -1144,15 +1144,18 @@ class SmarticoAPI {
 	public async leaderboardGet(
 		user_ext_id: string,
 		period_type_id?: LeaderBoardPeriodType,
-		prevPeriod: boolean = false,
+		prevPeriod: boolean | number = false,
 		force_language?: string,
 	): Promise<LeaderBoardDetails> {
+		// boolean keeps back-compat (false → current, true → previous);
+		// a number selects an arbitrary snapshot offset (1 = previous, 2 = the one before, …).
+		const snapshot_offset = typeof prevPeriod === 'number' ? prevPeriod : prevPeriod ? 1 : 0;
 		const message = this.buildMessage<GetLeaderBoardsRequest, GetLeaderBoardsResponse>(
 			user_ext_id,
 			ClassId.GET_LEADERS_BOARD_REQUEST,
 			{
 				period_type_id,
-				snapshot_offset: prevPeriod ? 1 : 0,
+				snapshot_offset,
 				include_users: true,
 			},
 		);
@@ -1184,11 +1187,36 @@ class SmarticoAPI {
 	public async leaderboardsGetT(
 		user_ext_id: string,
 		period_type_id: LeaderBoardPeriodType = LeaderBoardPeriodType.DAILY,
-		prevPeriod: boolean = false,
+		prevPeriod: boolean | number = false,
 	): Promise<LeaderBoardDetailsT> {
 		return getLeaderBoardTransform(await this.leaderboardGet(user_ext_id, period_type_id, prevPeriod));
 	}
 
+	public async leaderboardsGetList(
+		user_ext_id: string,
+		force_language?: string,
+	): Promise<LeaderBoardDetails[]> {
+		const message = this.buildMessage<GetLeaderBoardsRequest, GetLeaderBoardsResponse>(
+			user_ext_id,
+			ClassId.GET_LEADERS_BOARD_REQUEST,
+			{
+				// No period_type_id → the server returns every configured board.
+				// include_users: false → board metadata only (no positions / userPosition).
+				snapshot_offset: 0,
+				include_users: false,
+			},
+		);
+
+		const response = await this.send<GetLeaderBoardsResponse>(message, ClassId.GET_LEADERS_BOARD_RESPONSE, force_language);
+
+		// map is keyed by period_type_id; integer-like keys iterate in ascending order.
+		return Object.values(response.map || {});
+	}
+
+	public async leaderboardsGetListT(user_ext_id: string): Promise<LeaderBoardDetailsT[]> {
+		return (await this.leaderboardsGetList(user_ext_id)).map(getLeaderBoardTransform);
+	}
+
 	public async levelsGet(user_ext_id: string, force_language?: string): Promise<GetLevelMapResponse> {
 		const message = this.buildMessage<any, GetLevelMapResponse>(user_ext_id, ClassId.GET_LEVEL_MAP_REQUEST);
 		return await this.send<GetLevelMapResponse>(message, ClassId.GET_LEVEL_MAP_RESPONSE, force_language);
@@ -1572,7 +1600,6 @@ class SmarticoAPI {
 	}
 
 	public async avatarsCustomize(params: {
-		label_id: number;
 		user_id: number;
 		prompt_id: number;
 		avatar_url: string;
@@ -1581,7 +1608,8 @@ class SmarticoAPI {
 		return this.sendAvatarApi<AvatarCustomizeResponse>({
 			method: 'avatar-customize',
 			body: {
-				label_id: params.label_id,
+				// The server resolves label_id from label_api_key.
+				label_api_key: this.label_api_key,
 				user_id: params.user_id,
 				user_ext_id: this.tracker?.getExtUserId(),
 				brand_key: this.brand_api_key || this.tracker?.params?.brand_key,

package/src/WSAPI/WSAPIAvatars.ts

@@ -404,7 +404,6 @@ export class WSAPIAvatars extends WSAPIMiniGames {
 	 *
 	 * **Visitor mode**: not supported (throws).
 	 *
-	 * @param props.label_id        Numeric Smartico label (brand) ID the user belongs to.
 	 * @param props.user_id         Numeric Smartico user ID.
 	 * @param props.prompt_id       Style-prompt ID (`prompt_id`) from {@link getAvatarPrompts}.
 	 * @param props.avatar_url      CDN URL of the base avatar to customize.
@@ -414,13 +413,12 @@ export class WSAPIAvatars extends WSAPIMiniGames {
 	 *
 	 * @example
 	 * ```ts
-	 * // label_id / user_id identify the Smartico user being customized.
+	 * // user_id identifies the Smartico user being customized.
 	 * const prompts = await window._smartico.api.getAvatarPrompts();
 	 * const prompt = prompts[0];
 	 *
 	 * console.log('[smartico] generating avatar — show a spinner for ~5-20s and disable the Generate button');
 	 * const result = await window._smartico.api.avatarsCustomize({
-	 *   label_id,
 	 *   user_id,
 	 *   prompt_id: prompt.prompt_id,
 	 *   avatar_url: baseAvatar.avatar_url,
@@ -440,13 +438,12 @@ export class WSAPIAvatars extends WSAPIMiniGames {
 	 * ```
 	 */
 	public async avatarsCustomize(props: {
-		label_id: number;
 		user_id: number;
 		prompt_id: number;
 		avatar_url: string;
 		avatar_real_id: number;
 	}): Promise<AvatarCustomizeResponse> {
-		const required: (keyof typeof props)[] = ['label_id', 'user_id', 'prompt_id', 'avatar_url', 'avatar_real_id'];
+		const required: (keyof typeof props)[] = ['user_id', 'prompt_id', 'avatar_url', 'avatar_real_id'];
 		for (const field of required) {
 			if (!props[field]) {
 				throw new Error(`${field} is required`);

package/src/WSAPI/WSAPILeaderBoard.ts

@@ -20,7 +20,9 @@ export class WSAPILeaderBoard extends WSAPIGamePick {
 	 *
 	 * The leaderboard for each period type is configured separately by
 	 * the operator. A label may have any combination of DAILY, WEEKLY,
-	 * and MONTHLY boards configured (or none).
+	 * and MONTHLY boards configured (or none). To discover which boards
+	 * exist before loading any standings, call {@link getLeaderBoards}
+	 * (metadata only) and drive the tab selector from its `period_type_id`s.
 	 *
 	 * @remarks
 	 * **Return value note** — the runtime may return `undefined` if no
@@ -32,10 +34,13 @@ export class WSAPILeaderBoard extends WSAPIGamePick {
 	 * Pass a `periodType` from {@link LeaderBoardPeriodType}
 	 * (`DAILY = 1`, `WEEKLY = 2`, `MONTHLY = 3`). Pass
 	 * `getPreviousPeriod: true` to fetch the most-recently-ended
-	 * period's snapshot (yesterday's results, last week's results,
-	 * last month's results) instead of the current live period. The
-	 * SDK only exposes one period back — older snapshots are not
-	 * reachable through this method.
+	 * 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
@@ -89,10 +94,11 @@ export class WSAPILeaderBoard extends WSAPIGamePick {
 	 *                           Selects which pre-configured board to
 	 *                           fetch; the board itself is bound to one
 	 *                           period by the operator.
-	 * @param getPreviousPeriod  When `true`, returns the most recent
-	 *                           finalized snapshot for that period type
-	 *                           (e.g. last week's results). Defaults to
-	 *                           `false` (current in-progress period).
+	 * @param 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 resolving to `LeaderBoardDetailsT`.
 	 *                           **At runtime, may resolve to `undefined`**
 	 *                           when no board is configured for the
@@ -135,14 +141,85 @@ export class WSAPILeaderBoard extends WSAPIGamePick {
 	 * // const visitorBoard = await window._smartico.vapi('EN').getLeaderBoard(LeaderBoardPeriodType.DAILY);
 	 * ```
 	 */
-	public async getLeaderBoard(periodType: LeaderBoardPeriodType, getPreviousPeriod?: boolean): Promise<LeaderBoardDetailsT> {
-		// Cache per (periodType, current/previous) so switching tabs or
-		// current↔previous within the TTL doesn't return a colliding board.
-		const cacheKey = `${onUpdateContextKey.LeaderBoards}:${periodType}:${getPreviousPeriod ? 1 : 0}`;
+	public async getLeaderBoard(periodType: LeaderBoardPeriodType, getPreviousPeriod?: boolean | number): Promise<LeaderBoardDetailsT> {
+		// Resolve the snapshot offset: false/omitted → 0 (current), true → 1
+		// (previous), or an explicit number for older snapshots.
+		const offset = typeof getPreviousPeriod === 'number' ? getPreviousPeriod : getPreviousPeriod ? 1 : 0;
+		// Cache per (periodType, offset) so switching tabs or period within the
+		// TTL doesn't return a colliding board.
+		const cacheKey = `${onUpdateContextKey.LeaderBoards}:${periodType}:${offset}`;
 		return OCache.use(
 			cacheKey,
 			ECacheContext.WSAPI,
-			() => this.api.leaderboardsGetT(this.userExtId, periodType, getPreviousPeriod),
+			() => this.api.leaderboardsGetT(this.userExtId, periodType, offset),
+			CACHE_DATA_SEC,
+		);
+	}
+
+	/**
+	 * Returns the list of leaderboards the operator has configured for this
+	 * label — **metadata only, without participants**. Use it to discover
+	 * which boards exist (and their period types) so you can render the
+	 * board/tab selector, then load a specific board's standings on demand
+	 * with {@link getLeaderBoard}.
+	 *
+	 * This is the lightweight discovery counterpart to {@link getLeaderBoard}:
+	 * it issues one round-trip that returns every board's identity, name,
+	 * description, rules, `period_type_id`, and prize table, but **not** the
+	 * ranked players. Fetching the full standings for one board (the top-20
+	 * `users[]` and the caller's own `me` entry) is what {@link getLeaderBoard}
+	 * does per period.
+	 *
+	 * @remarks
+	 * **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 {@link 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
+	 * {@link 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.
+	 *
+	 * @returns Promise resolving to the array of configured boards
+	 *          (metadata only). Empty array when none are configured.
+	 *
+	 * @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');
+	 * ```
+	 */
+	public async getLeaderBoards(): Promise<LeaderBoardDetailsT[]> {
+		return OCache.use(
+			`${onUpdateContextKey.LeaderBoards}:list`,
+			ECacheContext.WSAPI,
+			() => this.api.leaderboardsGetListT(this.userExtId),
 			CACHE_DATA_SEC,
 		);
 	}

package/src/WSAPI/WSAPITypes.ts

@@ -1105,9 +1105,16 @@ export interface LeaderBoardDetailsT {
 	rules: string;
 	/** Period type this board is bound to ({@link LeaderBoardPeriodType}). */
 	period_type_id: LeaderBoardPeriodType;
+	/** Snapshot version. `0` for the live current period; a positive value
+	 * identifies a finalized previous-period snapshot (see `getPreviousPeriod`). */
+	version_id: number;
+	/** Snapshot creation timestamp (Unix ms). `0` for the live current period;
+	 * the finalization time for a previous-period snapshot. */
+	create_date: number;
 	/** Per-place prize table; the array length is the number of paid places. */
 	rewards: LeaderBoardsRewardsT[];
-	/** Top-20 ranked entries (server-capped), sorted by `position` ASC. */
+	/** Top-20 ranked entries (server-capped), sorted by `position` ASC.
+	 * Empty when fetched via `getLeaderBoards()` (metadata-only list). */
 	users: LeaderBoardUserT[];
 	/** Current user's own entry. `undefined` for visitor sessions.
 	 * For authenticated users, `position === -1` means the user is
@@ -1132,14 +1139,20 @@ export interface LeaderBoardsRewardsT {
 export interface LeaderBoardUserT {
 	/** Display username (operator-defined alias). */
 	public_username: string;
-	/** Resolved CDN URL for the participant's avatar. */
+	/** 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`. */
 	avatar_url: string;
+	/** The participant's level id — use it to resolve a level-based default
+	 * avatar when `avatar_url` is empty. */
+	level_id: number;
 	/** Rank in the leaderboard (DENSE_RANK over all participants).
 	 * `-1` on the `me` entry signals "unranked / outside the window". */
 	position: number;
 	/** Participant's points for this period. */
 	points: number;
-	/** `true` when this row is the current authenticated user. */
+	/** `true` when this row is the current authenticated user. Always `true`
+	 * on the `me` entry. */
 	is_me: boolean;
 }