@smartico/public-api 0.0.387 → 0.0.389

package/README.md

@@ -76,7 +76,7 @@ The SDK surface is split across one class per feature area, joined by an interna
 | **MiniGames / SAW** | [`WSAPIMiniGames`](docs/api/classes/WSAPIMiniGames.md) | `getMiniGames`, `getMiniGamesHistory`, `playMiniGame`, `miniGameWinAcknowledgeRequest`, `playMiniGameBatch` | [`getMiniGames`](docs/ui/minigames/UIGuide_getMiniGames.md) · [`getMiniGamesHistory`](docs/ui/minigames/UIGuide_getMiniGamesHistory.md) · [`playMiniGame`](docs/ui/minigames/UIGuide_playMiniGame.md) · [`playMiniGameBatch`](docs/ui/minigames/UIGuide_playMiniGameBatch.md) |
 | **Avatars** | [`WSAPIAvatars`](docs/api/classes/WSAPIAvatars.md) | `getAvatarsList`, `getAvatarsCustomized`, `getAvatarPrompts`, `setAvatar`, `avatarsCustomize` | [`getAvatarsList`](docs/ui/avatars/UIGuide_getAvatarsList.md) · [`getAvatarsCustomized`](docs/ui/avatars/UIGuide_getAvatarsCustomized.md) · [`getAvatarPrompts`](docs/ui/avatars/UIGuide_getAvatarPrompts.md) · [`setAvatar`](docs/ui/avatars/UIGuide_setAvatar.md) · [`avatarsCustomize`](docs/ui/avatars/UIGuide_avatarsCustomize.md) |
 | **Game Pick (sports / quiz)** | [`WSAPIGamePick`](docs/api/classes/WSAPIGamePick.md) | `gamePickGet*`, `gamePickSubmit*` (9 methods) | [`gamePickGetActiveRounds`](docs/ui/gamepick/UIGuide_gamePickGetActiveRounds.md) · [`gamePickGetActiveRound`](docs/ui/gamepick/UIGuide_gamePickGetActiveRound.md) · [`gamePickGetHistory`](docs/ui/gamepick/UIGuide_gamePickGetHistory.md) · [`gamePickGetBoard`](docs/ui/gamepick/UIGuide_gamePickGetBoard.md) · [`gamePickSubmitSelection`](docs/ui/gamepick/UIGuide_gamePickSubmitSelection.md) · [`gamePickSubmitSelectionQuiz`](docs/ui/gamepick/UIGuide_gamePickSubmitSelectionQuiz.md) · [`gamePickGetUserInfo`](docs/ui/gamepick/UIGuide_gamePickGetUserInfo.md) · [`gamePickGetGameInfo`](docs/ui/gamepick/UIGuide_gamePickGetGameInfo.md) · [`gamePickGetRoundInfoForUser`](docs/ui/gamepick/UIGuide_gamePickGetRoundInfoForUser.md) |
-| **Leaderboard** | [`WSAPILeaderBoard`](docs/api/classes/WSAPILeaderBoard.md) | `getLeaderBoard` | [`getLeaderBoard`](docs/ui/leaderboard/UIGuide_getLeaderBoard.md) |
+| **Leaderboard** | [`WSAPILeaderBoard`](docs/api/classes/WSAPILeaderBoard.md) | `getLeaderBoard`, `getLeaderBoards` | [`getLeaderBoard`](docs/ui/leaderboard/UIGuide_getLeaderBoard.md) |
 | **Inbox / Messages / Engagement** | [`WSAPIInbox`](docs/api/classes/WSAPIInbox.md) | `getInboxMessages`, `getInboxUnreadCount`, `getInboxMessageBody`, `markInboxMessageAsRead`, `markAllInboxMessagesAsRead`, `markUnmarkInboxMessageAsFavorite`, `deleteInboxMessage`, `deleteAllInboxMessages`, `reportImpressionEvent`, `reportClickEvent` | [`getInboxMessages`](docs/ui/inbox/UIGuide_getInboxMessages.md) · [`getInboxMessageBody`](docs/ui/inbox/UIGuide_getInboxMessageBody.md) · [`markInboxMessageAsRead`](docs/ui/inbox/UIGuide_markInboxMessageAsRead.md) · [`markUnmarkInboxMessageAsFavorite`](docs/ui/inbox/UIGuide_markUnmarkInboxMessageAsFavorite.md) · [`deleteInboxMessage`](docs/ui/inbox/UIGuide_deleteInboxMessage.md) |
 
 The shared return / param types live in [`WSAPITypes`](docs/api/classes/WSAPITypes.md). For the full type / enum / interface listing, see [`docs/api/globals.md`](docs/api/globals.md).

package/dist/CustomSections/AchCustomSection.d.ts

@@ -43,5 +43,6 @@ export declare enum LiquidEntityData {
     Badges = 9,
     Tournament = 10,
     Raffles = 11,
-    SingleRaffle = 12
+    SingleRaffle = 12,
+    Clans = 13
 }

package/dist/SmarticoAPI.d.ts

@@ -158,8 +158,10 @@ declare class SmarticoAPI {
     tournamentsGetInfo(user_ext_id: string, tournamentInstanceId: number, force_language?: string): Promise<GetTournamentInfoResponse>;
     tournamentsGetInfoT(user_ext_id: string, tournamentInstanceId: number): Promise<TTournamentDetailed>;
     clanTournamentGetPlayers(user_ext_id: string, tournament_instance_id: number, clan_id: number, force_language?: string): Promise<TClanTournamentPlayers>;
-    leaderboardGet(user_ext_id: string, period_type_id?: LeaderBoardPeriodType, prevPeriod?: boolean, force_language?: string): Promise<LeaderBoardDetails>;
-    leaderboardsGetT(user_ext_id: string, period_type_id?: LeaderBoardPeriodType, prevPeriod?: boolean): Promise<LeaderBoardDetailsT>;
+    leaderboardGet(user_ext_id: string, period_type_id?: LeaderBoardPeriodType, prevPeriod?: boolean | number, force_language?: string): Promise<LeaderBoardDetails>;
+    leaderboardsGetT(user_ext_id: string, period_type_id?: LeaderBoardPeriodType, prevPeriod?: boolean | number): Promise<LeaderBoardDetailsT>;
+    leaderboardsGetList(user_ext_id: string, force_language?: string): Promise<LeaderBoardDetails[]>;
+    leaderboardsGetListT(user_ext_id: string): Promise<LeaderBoardDetailsT[]>;
     levelsGet(user_ext_id: string, force_language?: string): Promise<GetLevelMapResponse>;
     levelsGetT(user_ext_id: string): Promise<TLevel[]>;
     getLevelCurrent(user_ext_id: string): Promise<TLevelCurrent>;
@@ -193,7 +195,6 @@ declare class SmarticoAPI {
     avatarsGetPrompts(user_ext_id: string): Promise<GetAvatarPromptsResponse>;
     avatarSetAvatar(user_ext_id: string, avatar_id: string, avatar_real_id: number): Promise<SetAvatarResponse>;
     avatarsCustomize(params: {
-        label_id: number;
         user_id: number;
         prompt_id: number;
         avatar_url: string;

package/dist/WSAPI/WSAPIAvatars.d.ts

@@ -354,7 +354,6 @@ export declare 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.
@@ -364,13 +363,12 @@ export declare 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,
@@ -390,7 +388,6 @@ export declare class WSAPIAvatars extends WSAPIMiniGames {
      * ```
      */
     avatarsCustomize(props: {
-        label_id: number;
         user_id: number;
         prompt_id: number;
         avatar_url: string;

package/dist/WSAPI/WSAPILeaderBoard.d.ts

@@ -12,7 +12,9 @@ export declare 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
@@ -24,10 +26,13 @@ export declare 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
@@ -81,10 +86,11 @@ export declare 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
@@ -127,5 +133,65 @@ export declare class WSAPILeaderBoard extends WSAPIGamePick {
      * // const visitorBoard = await window._smartico.vapi('EN').getLeaderBoard(LeaderBoardPeriodType.DAILY);
      * ```
      */
-    getLeaderBoard(periodType: LeaderBoardPeriodType, getPreviousPeriod?: boolean): Promise<LeaderBoardDetailsT>;
+    getLeaderBoard(periodType: LeaderBoardPeriodType, getPreviousPeriod?: boolean | number): Promise<LeaderBoardDetailsT>;
+    /**
+     * 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');
+     * ```
+     */
+    getLeaderBoards(): Promise<LeaderBoardDetailsT[]>;
 }

package/dist/WSAPI/WSAPITypes.d.ts

@@ -1044,9 +1044,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
@@ -1069,14 +1076,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;
 }
 /**