@smartico/public-api 0.0.386 → 0.0.388

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

@@ -953,6 +953,10 @@ export interface TMissionOrBadgeTask {
 	progress: number;
 	/** Reward for completing the task in points */
 	points_reward: number;
+	/** Reward for completing the task in gems */
+	gems_reward?: number;
+	/** Reward for completing the task in diamonds */
+	diamonds_reward?: number;
 	/** This is the total number of times the user needs to execute to complete task. e.g. he needs to bet 100 times. Here will be 100 */
 	execution_count_expected?: number;
 	/** This is the number of times the user has executed 'activity' of the task. e.g. he bet 5 times out of 100. Here will be 5 */
@@ -1101,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
@@ -1128,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;
 }
 
@@ -1780,9 +1797,9 @@ export interface TAvatarPrompt {
 	name: string;
 	/** Absolute CDN URL of the prompt's preview icon. */
 	icon_url: string;
-	/** Currency used to pay for the customization. `0` = points, `1` = gems, `2` = diamonds. */
+	/** Currency used to pay for the customization. `0` = points, `1` = gems, `2` = diamonds, `3` = free. A `cost_value` of `0` is also free. */
 	cost_currency_type_id: number;
-	/** Cost amount in the currency named by `cost_currency_type_id`. */
+	/** Cost amount in the currency named by `cost_currency_type_id`. `0` = free. */
 	cost_value: number;
 }
 

package/tsconfig.json

@@ -90,7 +90,9 @@
 			"src/Tournaments/GetClanTournamentPlayersResponse.ts",
 			"src/Avatars/AvatarDefinition.ts",
 			"src/Avatars/AvatarCustomized.ts",
-			"src/Avatars/AvatarPrompt.ts"
+			"src/Avatars/AvatarPrompt.ts",
+			"src/Avatars/AvatarCustomizeResponse.ts",
+			"src/Avatars/AvatarCustomizeErrorCode.ts"
 		],
 		"out": "docs/api",
 		"projectDocuments": ["docs/SmarticoObject.md", "docs/Callbacks.md", "docs/Transforms.md"],