@smartico/public-api 0.0.380 → 0.0.382

package/src/WSAPI/WSAPIJackpots.ts

@@ -28,23 +28,81 @@ export class WSAPIJackpots extends WSAPIClans {
 		OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.JackpotWinners);
 	}
 
-	/** Returns list of Jackpots that are active in the system and matching to the filter definition.
-	 * If filter is not provided, all active jackpots will be returned.
-	 * Filter can be used to get jackpots related to specific game or specific jackpot template.
-	 * You can call this method every second in order to get up to date information about current value of the jackpot(s) and present them to the end-users
+	/**
+	 * Returns the user-eligible jackpots active for the label, fused with their live
+	 * pot values. Each entry carries the static template (name, description, opt-in
+	 * state, eligible games, currency) plus a freshly-fetched `pot` snapshot.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.jackpotGet({ related_game_id: 'wooko-slot' }).then((result) => {
-	 *      console.log(result);
-	 * });
-	 * ```
+	 * Designed to be polled at high frequency (every 1 second is fine) — the SDK
+	 * splits the response into a 30-second template cache and a 1-second pot-value
+	 * cache so consumers can render a live-counting pot amount without hammering
+	 * the server for the static template data.
 	 *
-	 * **Example in the Visitor mode**:
-	 * ```
-	 * _smartico.vapi('EN').jackpotGet({ related_game_id: 'wooko-slot' }).then((result) => {
-	 *      console.log(result);
-	 * });
+	 * @remarks
+	 * **Preconditions**
+	 * - No prerequisite calls.
+	 * - Visitor mode supported via `_smartico.vapi(lang).jackpotGet(...)`.
+	 *
+	 * **Server-side eligibility filtering**
+	 * Jackpots are filtered server-side by the user's segments before being
+	 * returned. Templates the user is ineligible for never appear in this
+	 * response — there is no "locked" state to render. An empty result for a
+	 * known-good user typically means none of the configured templates match
+	 * the user's segments / level / brand.
+	 *
+	 * **Filter behavior**
+	 * Passing `related_game_id` returns only jackpots linked to that game (from
+	 * the operator's games catalog). Passing `jp_template_id` returns just that
+	 * single template. With no filter, all active templates the user is
+	 * eligible for are returned. Changing the filter between calls flushes both
+	 * the template cache and the pot cache.
+	 *
+	 * **Two-tier cache**
+	 * - Template definitions: 30 s cache. Re-fetched on filter change or when
+	 *   opt-in / opt-out / a jackpot-win push lands.
+	 * - Pot values: 1 s cache. Re-fetched on every call past the 1-second
+	 *   window so a 1 Hz poll renders a smoothly counting pot.
+	 *
+	 * **`jp_public_meta.custom_data`**
+	 * Server returns this as a JSON-encoded string; the SDK parses it inline so
+	 * consumers always receive either a parsed object or the raw string.
+	 *
+	 * **Personal vs MultiUser jackpots** (see {@link JackpotType})
+	 * - `MultiUser` (1) — shared pot; `registration_count` reflects real opted-in
+	 *   user count; temperature transitions fire push events.
+	 * - `Personal` (2) — independent per-user pot; `registration_count` is
+	 *   always 1; temperature push events are suppressed.
+	 *
+	 * **Refresh**
+	 * - `jp_status_id`, segment changes, and operator template edits surface
+	 *   after the 30 s template cache TTL.
+	 * - Opt-in / opt-out / jackpot-win push events all clear the template and
+	 *   pot caches — the next call re-fetches.
+	 *
+	 * **Visitor mode**: supported.
+	 *
+	 * **UI guidance**: see [UI Guide — `jackpotGet`](../../docs/ui/jackpots/UIGuide_jackpotGet.md).
+	 *
+	 * @param filter                     Optional filter narrowing the result set.
+	 * @param filter.related_game_id     Limit to jackpots linked to this game ID
+	 *                                    (from the operator's games catalog).
+	 * @param filter.jp_template_id      Limit to a single template.
+	 * @returns Array of {@link JackpotDetails} — empty if the user is eligible
+	 * for no active jackpots.
+	 *
+	 * @example
+	 * ```ts
+	 * // Poll every second for live pot counter
+	 * setInterval(async () => {
+	 *     const jackpots = await window._smartico.api.jackpotGet();
+	 *     for (const jp of jackpots) {
+	 *         console.log('[smartico] update pot widget for', jp.jp_public_meta.name, '— amount:', jp.pot.current_pot_amount_user_currency, jp.user_currency, '— temperature:', jp.pot.current_pot_temperature);
+	 *     }
+	 * }, 1000);
+	 *
+	 * // Filtered fetch for a specific game tile
+	 * const linked = await window._smartico.api.jackpotGet({ related_game_id: 'gold-slot2' });
+	 * console.log('[smartico] linked jackpots for game:', linked.length);
 	 * ```
 	 */
 	public async jackpotGet(filter?: { related_game_id?: string; jp_template_id?: number }): Promise<JackpotDetails[]> {
@@ -97,18 +155,68 @@ export class WSAPIJackpots extends WSAPIClans {
 	}
 
 	/**
-	 * Opt-in currently logged in user to the jackpot with the specified jp_template_id.
-	 * You may call jackpotGet method after doing optin to see that user is opted in to the jackpot.
+	 * Opts the authenticated user into a jackpot. From this point on, the user
+	 * contributes to the pot (per the template's `contribution_type` and
+	 * `contribution_value`) and is eligible to win when the pot explodes.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.jackpotOptIn({ jp_template_id: 123 }).then((result) => {
-	 *      console.log('Opted in to the jackpot');
-	 * });
-	 * ```
+	 * On success the SDK clears the jackpot caches — the next
+	 * {@link jackpotGet} call returns the updated `is_opted_in: true` and an
+	 * incremented `registration_count`.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 * - `jp_template_id` is mandatory — the SDK throws synchronously if missing.
+	 * - The jackpot must currently be active and the user must be in its
+	 *   eligibility segment. Ineligible jackpots are filtered out of
+	 *   {@link jackpotGet} entirely, so a card the user sees is opt-in-able.
+	 *
+	 * **Error handling**
+	 * The server returns a non-zero `errCode` with a human-readable `errMsg`
+	 * for any failure. Common causes:
+	 * - User is in a control group.
+	 * - Jackpot template is not active (status changed since the user opened
+	 *   the card).
+	 * - User is already opted in (the SDK has no client-side guard against a
+	 *   double-tap; the server enforces).
+	 * - DB race / generic server error.
+	 *
+	 * The SDK does NOT enumerate distinct numeric codes for each cause — branch
+	 * on `errCode === 0` for success and surface `errMsg` as-is for failures.
+	 *
+	 * **Idempotency / re-opt-in semantics**
+	 * - **Already opted in** → returns non-zero `errCode` ("User already opted in").
+	 * - **Previously opted in then opted out** → succeeds silently; the server
+	 *   re-activates the registration. This is not an error path — a user can
+	 *   freely cycle opt-in / opt-out.
+	 *
+	 * **Refresh after success**
+	 * - The SDK clears the template, pot, and winners caches.
+	 * - The next {@link jackpotGet} call returns `is_opted_in: true` for this
+	 *   template.
+	 *
+	 * **Side effects**
+	 * Fires a `JACKPOT_OPT_IN` engagement event (visible to operator-side
+	 * automation rules). Does NOT immediately move points / gems — contributions
+	 * happen per-bet via the user's gameplay, not on opt-in.
+	 *
+	 * **Visitor mode**: not supported.
 	 *
-	 * **Visitor mode: not supported**
+	 * **UI guidance**: see [UI Guide — `jackpotOptIn`](../../docs/ui/jackpots/UIGuide_jackpotOptIn.md).
 	 *
+	 * @param filter.jp_template_id  ID of the jackpot template to join.
+	 * @returns {@link JackpotsOptinResponse} — `errCode === 0` on success.
+	 *
+	 * @example
+	 * ```ts
+	 * const r = await window._smartico.api.jackpotOptIn({ jp_template_id: 42 });
+	 *
+	 * if (r.errCode === 0) {
+	 *     console.log('[smartico] opted in — refresh jackpot card to show opt-out CTA');
+	 * } else {
+	 *     console.error('[smartico] opt-in failed — show this message in an error toast:', r.errMsg);
+	 * }
+	 * ```
 	 */
 	public async jackpotOptIn(filter: { jp_template_id: number }): Promise<JackpotsOptinResponse> {
 		if (!filter.jp_template_id) {
@@ -121,18 +229,63 @@ export class WSAPIJackpots extends WSAPIClans {
 	}
 
 	/**
-	 * Opt-out currently logged in user from the jackpot with the specified jp_template_id.
-	 * You may call jackpotGet method after doing optout to see that user is not opted in to the jackpot.
+	 * Opts the authenticated user out of a jackpot. From this point on the user
+	 * no longer contributes to the pot and is not eligible to win.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.jackpotOptOut({ jp_template_id: 123 }).then((result) => {
-	 *      console.log('Opted out from the jackpot');
-	 * });
-	 * ```
+	 * The user can re-join later via {@link jackpotOptIn} — opt-out is not
+	 * permanent.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 * - `jp_template_id` is mandatory — the SDK throws synchronously if missing.
+	 *
+	 * **Error handling**
+	 * The server returns a non-zero `errCode` with a human-readable `errMsg` for
+	 * any failure. Common causes:
+	 * - User has never opted in OR is already opted out — server returns
+	 *   non-zero `errCode` for the "already opted out" case. Calling opt-out
+	 *   on a jackpot the user has never registered for typically returns
+	 *   success (the server finds no registration row to update).
+	 * - DB race / generic server error.
+	 *
+	 * Unlike {@link jackpotOptIn}, opt-out does NOT check the template's status
+	 * — the user can opt out of a jackpot that has been deactivated by the
+	 * operator.
 	 *
-	 * **Visitor mode: not supported**
+	 * **Idempotency**
+	 * - First opt-out → success.
+	 * - Second opt-out → non-zero `errCode` ("Already opted out").
+	 * - Opt-out of a never-joined jackpot → typically succeeds silently
+	 *   (no registration row to act on).
 	 *
+	 * **Refresh after success**
+	 * - The SDK clears the template, pot, and winners caches.
+	 * - The next {@link jackpotGet} call returns `is_opted_in: false` for this
+	 *   template and a decremented `registration_count`.
+	 *
+	 * **Side effects**
+	 * Fires a `JACKPOT_OPT_OUT` engagement event for operator-side automation
+	 * rules. The user's existing contributions to the current pot remain in
+	 * place — opt-out stops future contributions but does not refund past ones.
+	 *
+	 * **Visitor mode**: not supported.
+	 *
+	 * **UI guidance**: see [UI Guide — `jackpotOptOut`](../../docs/ui/jackpots/UIGuide_jackpotOptOut.md).
+	 *
+	 * @param filter.jp_template_id  ID of the jackpot template to leave.
+	 * @returns {@link JackpotsOptoutResponse} — `errCode === 0` on success.
+	 *
+	 * @example
+	 * ```ts
+	 * const r = await window._smartico.api.jackpotOptOut({ jp_template_id: 42 });
+	 *
+	 * if (r.errCode === 0) {
+	 *     console.log('[smartico] opted out — refresh jackpot card to show join CTA');
+	 * } else {
+	 *     console.error('[smartico] opt-out failed — show this message in an error toast:', r.errMsg);
+	 * }
+	 * ```
 	 */
 	public async jackpotOptOut(filter: { jp_template_id: number }): Promise<JackpotsOptoutResponse> {
 		if (!filter.jp_template_id) {
@@ -145,34 +298,75 @@ export class WSAPIJackpots extends WSAPIClans {
 	}
 
 	/**
-	 * Returns jackpot winners for the given `jp_template_id` (paginated on the server).
-	 * Default page size on the wire is 20; use `limit`, `offset`, and repeated calls to load more.
-	 * The full protocol response also includes `has_more`; this method returns only the `winners` array.
+	 * Returns past winners of a specific jackpot template, paginated. Use to
+	 * power a "Recent winners" panel inside the jackpot detail modal.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.getJackpotWinners({
-	 *      jp_template_id: 123,
-	 * }).then((result) => {
-	 *      console.log(result);
-	 * });
-	 * ```
+	 * **Important**: respect the `expose_winners_over_api` flag on the jackpot's
+	 * {@link JackpotDetails} before calling this method. The server-side handler
+	 * does NOT enforce that flag — it is a UI-only gate. Custom UIs that ignore
+	 * the flag will display winners the operator intended to keep private.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 * - `jp_template_id` is mandatory — the SDK throws synchronously if missing.
+	 * - The consumer SHOULD check
+	 *   {@link 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).
+	 *
+	 * @returns Array of {@link JackpotWinnerHistory} entries newest-first.
 	 *
-	 * **Visitor mode: not supported**
+	 * @example
+	 * ```ts
+	 * const [jp] = await window._smartico.api.jackpotGet({ jp_template_id: 42 });
 	 *
-	 * @param params - Jackpot winners parameters
-	 * @param params.jp_template_id - Jackpot template id (required; throws if missing)
-	 * @param params.limit - Page size (server default 20 when omitted)
-	 * @param params.offset - Offset into the winner list
+	 * 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 + ')');
+	 * ```
 	 */
-
 	public async 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[]> {
 		return OCache.use(
@@ -184,20 +378,62 @@ export class WSAPIJackpots extends WSAPIClans {
 	}
 
 	/**
-	 * Returns the eligible games for the jackpot with the specified jp_template_id.
+	 * Returns the casino games eligible to contribute to a specific jackpot —
+	 * the catalog the user must play to grow the pot. Use to power an
+	 * "Eligible games" carousel inside the jackpot detail modal.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.getJackpotEligibleGames({ jp_template_id: 123 }).then((result) => {
-	 *      console.log(result);
-	 * });
+	 * **Shortcut**: when the jackpot's
+	 * {@link JackpotDetails.ach_related_game_allow_all} flag is `true`, every
+	 * game in the operator catalog contributes — there's no point calling this
+	 * method (the result would be the full catalog). The default Smartico UI
+	 * hides the Eligible Games tab entirely in that case.
+	 *
+	 * @remarks
+	 * **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).
+	 *
+	 * @returns {@link TGetJackpotEligibleGamesResponse} —
+	 * `{ eligible_games: JackpotEligibleGame[] }`.
+	 *
+	 * @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');
 	 * ```
-	 * 
-	 * **Visitor mode: not supported**
-	 * 
 	 */
-
-	public async getJackpotEligibleGames({ jp_template_id, onUpdate } : { jp_template_id: number, onUpdate?: () => void }): Promise<TGetJackpotEligibleGamesResponse> {
+	public async getJackpotEligibleGames({ jp_template_id, onUpdate } : {
+		/** Jackpot template ID (required). */
+		jp_template_id: number,
+		/** Optional callback; not auto-invoked today. */
+		onUpdate?: () => void,
+	}): Promise<TGetJackpotEligibleGamesResponse> {
 		if (onUpdate) {
 			this.onUpdateCallback.set(onUpdateContextKey.JackpotEligibleGames, onUpdate);
 		}

package/src/WSAPI/WSAPILeaderBoard.ts

@@ -12,21 +12,135 @@ import { WSAPIGamePick } from './WSAPIGamePick';
 /** @group LeaderBoard */
 export class WSAPILeaderBoard extends WSAPIGamePick {
 	/**
-	 * Returns the leaderboard for the current type (default is Daily). If getPreviousPeriod is passed as true, a leaderboard for the previous period for the current type will be returned.
-	 * For example, if the type is Weekly and getPreviousPeriod is true, a leaderboard for the previous week will be returned.
+	 * 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.
+	 * Use this to power a leaderboard page with daily / weekly /
+	 * monthly tabs.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.getLeaderBoard(1).then((result) => {
-	 *     console.log(result);
-	 * });
-	 * ```
+	 * 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).
 	 *
-	 * **Example in the Visitor mode**:
-	 * ```
-	 * _smartico.vapi('EN').getLeaderBoard(1).then((result) => {
-	 *    console.log(result);
-	 * });
+	 * @remarks
+	 * **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 {@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.
+	 *
+	 * **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 — single shared key (known limitation)**
+	 * The SDK caches the response for 30 seconds under a SINGLE shared
+	 * key — calling `getLeaderBoard(DAILY)` followed by
+	 * `getLeaderBoard(WEEKLY)` within the same 30 s window returns the
+	 * cached DAILY result for the WEEKLY call. Same applies to
+	 * switching `getPreviousPeriod`. To force a fresh fetch when
+	 * switching periods or current/previous, call
+	 * `_smartico.api.clearCaches()` before the second call, or simply
+	 * wait out the TTL.
+	 *
+	 * **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.
+	 *
+	 * @param periodType         The board's period type
+	 *                           ({@link LeaderBoardPeriodType}).
+	 *                           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).
+	 * @returns                  Promise resolving to `LeaderBoardDetailsT`.
+	 *                           **At runtime, may resolve to `undefined`**
+	 *                           when no board is configured for the
+	 *                           requested period type — guard against it.
+	 *
+	 * @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 — but bust the cache first to avoid the shared-key collision.
+	 * await window._smartico.api.clearCaches();
+	 * 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);
 	 * ```
 	 */
 	public async getLeaderBoard(periodType: LeaderBoardPeriodType, getPreviousPeriod?: boolean): Promise<LeaderBoardDetailsT> {