@smartico/public-api 0.0.380 → 0.0.382

package/src/WSAPI/WSAPIGamePick.ts

@@ -12,37 +12,65 @@ import { WSAPIAvatars } from './WSAPIAvatars';
 /** @group GamePick */
 export class WSAPIGamePick extends WSAPIAvatars {
 	/**
-	 * Returns the active rounds for the specified MatchX or Quiz game.
-	 * Each round includes its events (matches/questions) along with the current user's selections and scores.
-	 *
-	 * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-	 *
-	 * **Response** `GamesApiResponse<GamePickRound[]>`:
-	 * - `errCode` - 0 on success
-	 * - `data` - Array of rounds, each containing:
-	 *   - `round_id`, `round_name` - Round identifier and display name
-	 *   - `open_date`, `last_bet_date` - Timestamps (ms) for round open and betting deadline
-	 *   - `is_active_now`, `is_resolved` - Round state flags
-	 *   - `round_status_id` - Round status: -1 (active), 2 (no more bets), 3 (all events resolved), 4 (round resolved)
-	 *   - `score_full_win`, `score_part_win`, `score_lost` - Scoring rules per prediction outcome
-	 *   - `user_score` - Current user's total score in this round
-	 *   - `user_placed_bet` - Whether the user has submitted predictions
-	 *   - `has_open_for_bet_events` - Whether there are events still open for betting
-	 *   - `events[]` - Array of events with `gp_event_id`, `market_type_id`, `event_meta` (team names, images, sport), `match_date`, `is_open_for_bets`, `odds_details`, and user selection fields
-	 *
-	 * **Example**:
+	 * Returns every open round for a MatchX or Quiz game template, with the full
+	 * event list (matches / questions) and the current user's selections per event.
+	 *
+	 * Use to power the rounds-lobby screen — typically a list of round cards a user
+	 * can tap into to make predictions. For a single round, use
+	 * {@link gamePickGetActiveRound} (lighter payload when only one round is shown).
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated.
+	 * - `saw_template_id` must reference a MatchX or Quiz game template. The SDK
+	 *   throws synchronously if it's missing.
+	 *
+	 * **Transport**
+	 * Game Pick methods are HTTP REST calls to a separate Game Pick games server
+	 * (not the main WebSocket). One consequence: there is no SDK cache and no push
+	 * subscription — every call is a fresh server roundtrip.
+	 *
+	 * **Round status**
+	 * Each round's `round_status_id` is a {@link GPRoundStatus} value. Rounds with
+	 * status `NoEventsDefined` (1) are filtered out server-side and never appear
+	 * here. Other values: `Other` (-1, normally open), `NoMoreBetsAllowed` (2),
+	 * `AllEventsResolved_ButNotRound` (3), `RoundResolved` (4 — appears here only
+	 * briefly during transition; use {@link gamePickGetHistory} for resolved rounds).
+	 *
+	 * **Error codes** (in `errCode`)
+	 * - `0` — success.
+	 * - `100002` — template not found (the `saw_template_id` doesn't reference a
+	 *   MatchX/Quiz game).
+	 * - `100003` — no open rounds available for this template right now.
+	 * - `100000` — auth hash invalid; SDK session needs re-initialization.
+	 * - `100004` — generic server error.
+	 *
+	 * **Refresh**
+	 * - No cache; every call is live.
+	 * - No push subscription. Poll while the user is on the screen if you need
+	 *   live round-status changes (typically every 30–60 s is enough).
+	 *
+	 * **Visitor mode**: not supported. The SDK throws synchronously on visitor
+	 * sessions.
+	 *
+	 * **UI guidance**: see [UI Guide — `gamePickGetActiveRounds`](../../docs/ui/gamepick/UIGuide_gamePickGetActiveRounds.md).
+	 *
+	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @returns Wrapped {@link GamesApiResponse} of {@link GamePickRound} array.
+	 *
+	 * @example
+	 * ```ts
+	 * const r = await window._smartico.api.gamePickGetActiveRounds({ saw_template_id: 1083 });
+	 *
+	 * if (r.errCode !== 0) {
+	 *     console.error('[smartico] active rounds fetch failed — show empty rounds lobby:', r.errMessage);
+	 *     return;
+	 * }
+	 *
+	 * for (const round of r.data ?? []) {
+	 *     console.log('[smartico] render a round card:', round.round_name, '— events:', round.events.length, 'user has placed bet:', round.user_placed_bet);
+	 * }
 	 * ```
-	 * _smartico.api.gamePickGetActiveRounds({
-	 *      saw_template_id: 1083,
-	 * }).then((result) => {
-	 *      console.log(result.data); // GamePickRound[]
-	 *      result.data.forEach(round => {
-	 *          console.log(round.round_name, round.events.length);
-	 *      });
-	 * });
-	 * ```
-	 *
-	 * **Visitor mode: not supported**
 	 */
 	public async gamePickGetActiveRounds(props: GamePickRequestParams): Promise<GamesApiResponse<GamePickRound[]>> {
 		if (!props.saw_template_id) {
@@ -52,29 +80,56 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	}
 
 	/**
-	 * Returns a single active round for the specified MatchX or Quiz game.
-	 * The round includes full event details with the current user's selections.
-	 *
-	 * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-	 * @param props.round_id - The specific round to retrieve
-	 *
-	 * **Response** `GamesApiResponse<GamePickRound>`:
-	 * - `errCode` - 0 on success
-	 * - `data` - Single round object with the same structure as in `gamePickGetActiveRounds`,
-	 *   including `events[]` with full event details, user selections, and resolution info
-	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.gamePickGetActiveRound({
-	 *      saw_template_id: 1083,
-	 *      round_id: 31652,
-	 * }).then((result) => {
-	 *      console.log(result.data.round_name, result.data.events.length);
-	 *      console.log(result.data.user_score, result.data.user_placed_bet);
+	 * Returns a single round (events, user selections, scoring rules) for a
+	 * MatchX or Quiz game. Use to power the round-detail / prediction-input
+	 * screen the user lands on after picking a round from the lobby.
+	 *
+	 * Same shape as one entry of {@link gamePickGetActiveRounds}; cheaper when the
+	 * UI only shows one round at a time.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 * - `saw_template_id` and `round_id` are mandatory — the SDK throws if either
+	 *   is missing.
+	 *
+	 * **Error codes** (in `errCode`)
+	 * - `0` — success.
+	 * - `4` — round / event not found (e.g. round resolved after the last
+	 *   `gamePickGetActiveRounds` poll); non-fatal — retry after a fresh active-
+	 *   rounds fetch.
+	 * - `100002` — template not found.
+	 * - `100000` — auth hash invalid.
+	 * - `100004` — generic server error.
+	 *
+	 * **Refresh**
+	 * - No cache; every call is live.
+	 * - Re-call after {@link gamePickSubmitSelection} or
+	 *   {@link gamePickSubmitSelectionQuiz} to surface the persisted predictions.
+	 * - Poll while the user is on the prediction screen if event resolution
+	 *   updates are needed (typically every 30–60 s).
+	 *
+	 * **Visitor mode**: not supported.
+	 *
+	 * **UI guidance**: see [UI Guide — `gamePickGetActiveRound`](../../docs/ui/gamepick/UIGuide_gamePickGetActiveRound.md).
+	 *
+	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @param props.round_id         ID of the round to fetch.
+	 * @returns Wrapped {@link GamesApiResponse} of a single {@link GamePickRound}.
+	 *
+	 * @example
+	 * ```ts
+	 * const r = await window._smartico.api.gamePickGetActiveRound({
+	 *     saw_template_id: 1083,
+	 *     round_id:        31652,
 	 * });
-	 * ```
 	 *
-	 * **Visitor mode: not supported**
+	 * if (r.errCode === 0 && r.data) {
+	 *     console.log('[smartico] render round detail page —', r.data.round_name, '— user has placed bet:', r.data.user_placed_bet, 'score so far:', r.data.user_score);
+	 * } else {
+	 *     console.error('[smartico] round fetch failed — bounce back to the lobby and refresh:', r.errMessage);
+	 * }
+	 * ```
 	 */
 	public async gamePickGetActiveRound(props: GamePickRoundRequestParams): Promise<GamesApiResponse<GamePickRound>> {
 		if (!props.saw_template_id) {
@@ -87,29 +142,52 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	}
 
 	/**
-	 * Returns the history of all rounds (including resolved ones) for the specified MatchX or Quiz game.
-	 * Each round contains full event details with results and the current user's predictions.
+	 * Returns the full round history (active + resolved) for a MatchX or Quiz game
+	 * template, newest-first. Each round carries the user's predictions plus the
+	 * server-resolved outcome on each event.
 	 *
-	 * @param props.saw_template_id - The ID of the MatchX or Quiz game template
+	 * Use to power a "Past predictions" / history tab. For just the open rounds,
+	 * use {@link gamePickGetActiveRounds} (faster — skips resolved data).
 	 *
-	 * **Response** `GamesApiResponse<GamePickRound[]>`:
-	 * - `errCode` - 0 on success
-	 * - `data` - Array of rounds ordered by `round_row_id` descending (newest first).
-	 *   Each round has the same structure as in `gamePickGetActiveRounds`, including resolved events
-	 *   with `resolution_type_id` (0=None, 2=Lost, 3=PartialWin, 4=FullWin) and `resolution_score`
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
 	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.gamePickGetHistory({
-	 *      saw_template_id: 1083,
-	 * }).then((result) => {
-	 *      result.data.forEach(round => {
-	 *          console.log(round.round_name, 'Score:', round.user_score, 'Resolved:', round.is_resolved);
-	 *      });
-	 * });
-	 * ```
+	 * **Sort order**
+	 * Server returns rounds newest-first. No client-side sort needed.
+	 *
+	 * **Per-event resolution**
+	 * Each event in the rounds carries `resolution_type_id` — values are from
+	 * {@link GamePickResolutionType}: `None` (0, not yet resolved), `Lost` (2),
+	 * `PartialWin` (3), `FullWin` (4). Use these to render result badges on
+	 * each event row.
+	 *
+	 * **Error codes** (in `errCode`)
+	 * - `0` — success.
+	 * - `100002` — template not found.
+	 * - `100000` — auth hash invalid.
+	 * - `100004` — generic server error.
+	 *
+	 * **Refresh**
+	 * - No cache.
+	 * - No push subscription. Re-call when the user opens the history tab.
+	 *
+	 * **Visitor mode**: not supported.
 	 *
-	 * **Visitor mode: not supported**
+	 * **UI guidance**: see [UI Guide — `gamePickGetHistory`](../../docs/ui/gamepick/UIGuide_gamePickGetHistory.md).
+	 *
+	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @returns Wrapped {@link GamesApiResponse} of {@link GamePickRound} array,
+	 * newest-first.
+	 *
+	 * @example
+	 * ```ts
+	 * const r = await window._smartico.api.gamePickGetHistory({ saw_template_id: 1083 });
+	 *
+	 * for (const round of r.data ?? []) {
+	 *     console.log('[smartico] history row —', round.round_name, 'score:', round.user_score, 'resolved:', round.is_resolved);
+	 * }
+	 * ```
 	 */
 	public async gamePickGetHistory(props: GamePickRequestParams): Promise<GamesApiResponse<GamePickRound[]>> {
 		if (!props.saw_template_id) {
@@ -119,36 +197,66 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	}
 
 	/**
-	 * Returns the leaderboard for a specific round within a MatchX or Quiz game.
-	 * Use `round_id = -1` (AllRoundsGameBoardID) to get the season/overall leaderboard across all rounds.
-	 *
-	 * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-	 * @param props.round_id - The round to get the leaderboard for. Use -1 for overall/seasonal leaderboard
-	 *
-	 * **Response** `GamesApiResponse<GamePickRoundBoard>`:
-	 * - `errCode` - 0 on success
-	 * - `data` - Leaderboard object containing:
-	 *   - Round base fields (`round_id`, `round_name`, `open_date`, `last_bet_date`, etc.)
-	 *   - `users[]` - Ranked list of players, each with:
-	 *     - `ext_user_id`, `int_user_id` - User identifiers
-	 *     - `public_username`, `avatar_url` - Display info (usernames may be masked based on label settings)
-	 *     - `gp_position` - Leaderboard rank (null if not yet ranked)
-	 *     - `resolution_score` - Total score in this round
-	 *     - `full_wins_count`, `part_wins_count`, `lost_count` - Prediction outcome counts
-	 *   - `my_user` - Current user's entry (same fields as above), or null if user hasn't participated
-	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.gamePickGetBoard({
-	 *      saw_template_id: 1083,
-	 *      round_id: 31652,
-	 * }).then((result) => {
-	 *      console.log('Top players:', result.data.users);
-	 *      console.log('My position:', result.data.my_user?.gp_position);
+	 * Returns the leaderboard for a MatchX or Quiz game round — ranked list of
+	 * players plus the current user's entry (`my_user`). Pass `round_id: -1` for
+	 * the season / overall leaderboard across every round in the template.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 *
+	 * **`round_id` semantics**
+	 * - Positive `round_id` — per-round leaderboard scoped to that round's events.
+	 * - `-1` — season / overall leaderboard aggregating scores across every round
+	 *   of the template.
+	 *
+	 * **`my_user`**
+	 * The current user's entry is returned separately from the `users[]` array
+	 * — `my_user` may be `null` if the user has never made a prediction on this
+	 * round / template. Use it to render the user's rank in a sticky footer or
+	 * "you are here" highlight regardless of pagination.
+	 *
+	 * **Username masking**
+	 * `public_username` on other players may be masked / anonymized by operator
+	 * label settings. Always pair with `avatar_url` so the user can recognize
+	 * themselves in the ranking by avatar even when usernames are hidden.
+	 *
+	 * **Error codes** (in `errCode`)
+	 * - `0` — success.
+	 * - `100002` — template not found.
+	 * - `100000` — auth hash invalid.
+	 * - `100004` — generic server error.
+	 *
+	 * **Refresh**
+	 * - No cache.
+	 * - No push subscription. Poll while the leaderboard is visible
+	 *   (every 30–60 s) if you want live rank updates after match
+	 *   resolution.
+	 *
+	 * **Visitor mode**: not supported.
+	 *
+	 * **UI guidance**: see [UI Guide — `gamePickGetBoard`](../../docs/ui/gamepick/UIGuide_gamePickGetBoard.md).
+	 *
+	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @param props.round_id         Round ID, or `-1` for the season leaderboard.
+	 * @returns Wrapped {@link GamesApiResponse} of {@link GamePickRoundBoard}.
+	 *
+	 * @example
+	 * ```ts
+	 * const r = await window._smartico.api.gamePickGetBoard({
+	 *     saw_template_id: 1083,
+	 *     round_id:        -1, // season leaderboard
 	 * });
-	 * ```
 	 *
-	 * **Visitor mode: not supported**
+	 * if (r.errCode === 0 && r.data) {
+	 *     console.log('[smartico] render leaderboard rows for top', r.data.users.length, 'players');
+	 *     if (r.data.my_user) {
+	 *         console.log('[smartico] pin "you are rank #' + r.data.my_user.gp_position + '" footer to bottom');
+	 *     } else {
+	 *         console.log('[smartico] user not ranked — render "Play a round to join the leaderboard" CTA');
+	 *     }
+	 * }
+	 * ```
 	 */
 	public async gamePickGetBoard(props: GamePickRoundRequestParams): Promise<GamesApiResponse<GamePickRoundBoard>> {
 		if (!props.saw_template_id) {
@@ -161,43 +269,107 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	}
 
 	/**
-	 * Submits score predictions for a round in a MatchX game.
-	 * Sends the round object with user selections for all events at once.
-	 * Each event must include `team1_user_selection` and `team2_user_selection` representing predicted scores.
-	 * If the user hasn't placed bets before, one game attempt (spin) will be consumed.
-	 * Predictions can be edited until each match starts (if `allow_edit_answers` is enabled on the round).
-	 *
-	 * @param props.saw_template_id - The ID of the MatchX game template
-	 * @param props.round - Round object containing `round_id` and `events[]`. Typically obtained from `gamePickGetActiveRound`
-	 *   and modified with user predictions. Each event needs: `gp_event_id`, `team1_user_selection`, `team2_user_selection`
-	 *
-	 * **Response** `GamesApiResponse<GamePickRound>`:
-	 * - `errCode` - 0 on success. Non-zero codes indicate errors (e.g. not enough points/attempts)
-	 * - `data` - Updated round with all events reflecting the submitted selections.
-	 *   `user_placed_bet` will be `true`, `has_not_submitted_changes` will be `false`
-	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.gamePickGetActiveRound({
-	 *      saw_template_id: 1190,
-	 *      round_id: 38665,
-	 * }).then((roundData) => {
-	 *      const round = roundData.data;
-	 *      round.events = round.events.map(e => ({
-	 *          gp_event_id: e.gp_event_id,
-	 *          team1_user_selection: 1,
-	 *          team2_user_selection: 0,
-	 *      }));
-	 *      _smartico.api.gamePickSubmitSelection({
-	 *          saw_template_id: 1190,
-	 *          round: round,
-	 *      }).then((result) => {
-	 *          console.log(result.data.user_placed_bet); // true
-	 *      });
+	 * Submits all score predictions for a round in a MatchX game in one shot.
+	 * Each event in the round must carry `team1_user_selection` and
+	 * `team2_user_selection` (the predicted scores).
+	 *
+	 * On the user's FIRST submit for a round, the server charges one buy-in (one
+	 * "spin" / one currency deduction based on the template's `saw_buyin_type_id`).
+	 * Subsequent edits within the same round are free and only persist changed
+	 * selections.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 * - `saw_template_id` and `props.round.round_id` are mandatory — SDK throws if
+	 *   either is missing.
+	 * - Each event passed must include `gp_event_id` and the two
+	 *   `team{1,2}_user_selection` fields. Missing events default to "no change".
+	 *
+	 * **Error codes** (in `errCode`)
+	 * - `0` — success; the response `data` is the updated round with
+	 *   `user_placed_bet === true` and `has_not_submitted_changes === false`.
+	 * - `3` (`NoBetsUpdatedOnSubmit`) — submit produced no changes, OR every event
+	 *   is past its `last_bet_date` deadline. The buy-in is NOT consumed; the
+	 *   current round is still returned in `data`.
+	 * - `4` — round / event not found; refresh state and retry.
+	 * - `100002` — template not found.
+	 * - `100000` — auth hash invalid.
+	 * - `100004` — generic server error.
+	 *
+	 * Buy-in failures pass through the {@link SAWSpinErrorCode} values on first
+	 * submit:
+	 * - `40001` — no spins left (when `saw_buyin_type_id` is Spins).
+	 * - `40003` — insufficient points.
+	 * - `40004` — global max-spins cap hit.
+	 * - `40007` — template outside its active date window.
+	 * - `40009` — user excluded by segment rule.
+	 * - `40011` — insufficient gems.
+	 * - `40012` — insufficient diamonds.
+	 *
+	 * **Idempotency**
+	 * Re-submitting identical selections returns `errCode: 3` (no changes); the
+	 * buy-in is consumed exactly once per round-per-user. Re-submitting after
+	 * `last_bet_date` also returns `errCode: 3` without consuming the buy-in.
+	 *
+	 * **Side effects**
+	 * - First successful submit deducts the buy-in (Points / Gems / Diamonds /
+	 *   one Spin) per `saw_buyin_type_id`.
+	 * - Reports a `minigame_matchx_prediction` event to the operator's event log.
+	 * - Updates the round's participant counter (`users_cnt`) and per-event
+	 *   counters (`num_users`).
+	 * - Score is awarded after the operator resolves the round
+	 *   ({@link GPRoundStatus} = `RoundResolved`).
+	 *
+	 * **Visitor mode**: not supported.
+	 *
+	 * **UI guidance**: see [UI Guide — `gamePickSubmitSelection`](../../docs/ui/gamepick/UIGuide_gamePickSubmitSelection.md).
+	 *
+	 * @param props.saw_template_id  ID of the MatchX game template.
+	 * @param props.round            Round object with `round_id` + `events[]`
+	 *                                carrying the user's score predictions.
+	 * @returns Wrapped {@link GamesApiResponse} with the updated round.
+	 *
+	 * @example
+	 * ```ts
+	 * const ar = await window._smartico.api.gamePickGetActiveRound({
+	 *     saw_template_id: 1190,
+	 *     round_id:        38665,
+	 * });
+	 * if (ar.errCode !== 0 || !ar.data) {
+	 *     console.error('[smartico] could not fetch round to submit — show error and bounce back');
+	 *     return;
+	 * }
+	 *
+	 * const round = ar.data;
+	 * round.events = round.events.map(e => ({
+	 *     gp_event_id:          e.gp_event_id,
+	 *     team1_user_selection: 1,
+	 *     team2_user_selection: 0,
+	 * }));
+	 *
+	 * const r = await window._smartico.api.gamePickSubmitSelection({
+	 *     saw_template_id: 1190,
+	 *     round,
 	 * });
-	 * ```
 	 *
-	 * **Visitor mode: not supported**
+	 * switch (r.errCode) {
+	 *     case 0:
+	 *         console.log('[smartico] predictions saved — show confirmation, refresh leaderboard');
+	 *         break;
+	 *     case 3:
+	 *         console.log('[smartico] nothing changed (or all events closed) — silent no-op');
+	 *         break;
+	 *     case 40001:
+	 *     case 40003:
+	 *     case 40011:
+	 *     case 40012:
+	 *         console.error('[smartico] insufficient balance / spins — show top-up CTA:', r.errMessage);
+	 *         break;
+	 *     default:
+	 *         console.error('[smartico] submit failed — show generic error toast:', r.errMessage);
+	 * }
+	 * ```
 	 */
 	public async gamePickSubmitSelection(props: GamePickRequestParams & { round: Partial<GamePickRound> }): Promise<GamesApiResponse<GamePickRound>> {
 		if (!props.saw_template_id) {
@@ -210,42 +382,83 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	}
 
 	/**
-	 * Submits answers for a round in a Quiz game.
-	 * Sends the round object with user answers for all events at once.
-	 * Each event must include `user_selection` with the answer value (e.g. '1', '2', 'x', 'yes', 'no' — depending on the market type).
-	 * If the user hasn't placed bets before, one game attempt (spin) will be consumed.
-	 * Answers can be edited until each match starts (if `allow_edit_answers` is enabled on the round).
-	 *
-	 * @param props.saw_template_id - The ID of the Quiz game template
-	 * @param props.round - Round object containing `round_id` and `events[]`. Typically obtained from `gamePickGetActiveRound`
-	 *   and modified with user answers. Each event needs: `gp_event_id`, `user_selection`
-	 *
-	 * **Response** `GamesApiResponse<GamePickRound>`:
-	 * - `errCode` - 0 on success. Non-zero codes indicate errors (e.g. not enough points/attempts)
-	 * - `data` - Updated round with all events reflecting the submitted answers.
-	 *   `user_placed_bet` will be `true`, `has_not_submitted_changes` will be `false`
-	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.gamePickGetActiveRound({
-	 *      saw_template_id: 1183,
-	 *      round_id: 37974,
-	 * }).then((roundData) => {
-	 *      const round = roundData.data;
-	 *      round.events = round.events.map(e => ({
-	 *          gp_event_id: e.gp_event_id,
-	 *          user_selection: 'x',
-	 *      }));
-	 *      _smartico.api.gamePickSubmitSelectionQuiz({
-	 *          saw_template_id: 1183,
-	 *          round: round,
-	 *      }).then((result) => {
-	 *          console.log(result.data.user_placed_bet); // true
-	 *      });
+	 * Submits all quiz answers for a round in one shot. Each event in the round
+	 * must carry `user_selection` (the answer value — typically `"1"` / `"2"` /
+	 * `"x"` for 1×2 markets, `"yes"` / `"no"` for binary markets, or any
+	 * operator-defined string for custom markets).
+	 *
+	 * Same first-submit buy-in behavior as {@link gamePickSubmitSelection} — one
+	 * buy-in is charged on the first successful submit; subsequent edits within
+	 * the same round are free.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 * - `saw_template_id` and `props.round.round_id` are mandatory — SDK throws if
+	 *   either is missing.
+	 * - Each event must include `gp_event_id` and `user_selection`. Missing
+	 *   events default to "no change".
+	 *
+	 * **Error codes** (in `errCode`)
+	 * - `0` — success.
+	 * - `3` (`NoBetsUpdatedOnSubmit`) — no changes, OR every event past
+	 *   `last_bet_date`. Buy-in NOT consumed; current round returned in `data`.
+	 * - `4` — round / event not found.
+	 * - `100002` — template not found.
+	 * - `100000` — auth hash invalid.
+	 * - `100004` — generic server error.
+	 *
+	 * Buy-in failures use the same {@link SAWSpinErrorCode} pass-through values
+	 * as {@link gamePickSubmitSelection} — see that method's TSDoc for the
+	 * `40001` / `40003` / `40004` / `40007` / `40009` / `40011` / `40012`
+	 * semantics.
+	 *
+	 * **Idempotency**: identical to {@link gamePickSubmitSelection} — re-submit
+	 * returns `errCode: 3` and never double-charges the buy-in.
+	 *
+	 * **Side effects**: identical to {@link gamePickSubmitSelection}, with the
+	 * reported event being `minigame_quiz_prediction` instead of
+	 * `minigame_matchx_prediction`.
+	 *
+	 * **Visitor mode**: not supported.
+	 *
+	 * **UI guidance**: see [UI Guide — `gamePickSubmitSelectionQuiz`](../../docs/ui/gamepick/UIGuide_gamePickSubmitSelectionQuiz.md).
+	 *
+	 * @param props.saw_template_id  ID of the Quiz game template.
+	 * @param props.round            Round object with `round_id` + `events[]`
+	 *                                carrying the user's answer selections.
+	 * @returns Wrapped {@link GamesApiResponse} with the updated round.
+	 *
+	 * @example
+	 * ```ts
+	 * const ar = await window._smartico.api.gamePickGetActiveRound({
+	 *     saw_template_id: 1183,
+	 *     round_id:        37974,
+	 * });
+	 * if (ar.errCode !== 0 || !ar.data) {
+	 *     console.error('[smartico] could not fetch round to submit answers — show error');
+	 *     return;
+	 * }
+	 *
+	 * const round = ar.data;
+	 * round.events = round.events.map(e => ({
+	 *     gp_event_id:    e.gp_event_id,
+	 *     user_selection: 'x',
+	 * }));
+	 *
+	 * const r = await window._smartico.api.gamePickSubmitSelectionQuiz({
+	 *     saw_template_id: 1183,
+	 *     round,
 	 * });
-	 * ```
 	 *
-	 * **Visitor mode: not supported**
+	 * if (r.errCode === 0) {
+	 *     console.log('[smartico] quiz answers saved — show confirmation');
+	 * } else if (r.errCode === 3) {
+	 *     console.log('[smartico] nothing changed — silent no-op');
+	 * } else {
+	 *     console.error('[smartico] quiz submit failed:', r.errMessage);
+	 * }
+	 * ```
 	 */
 	public async gamePickSubmitSelectionQuiz(props: GamePickRequestParams & { round: Partial<GamePickRound> }): Promise<GamesApiResponse<GamePickRound>> {
 		if (!props.saw_template_id) {
@@ -258,35 +471,51 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	}
 
 	/**
-	 * Returns the current user's profile information within the specified MatchX or Quiz game.
-	 * The user record is synced from the Smartico platform into the games DB (synced every 1 minute).
-	 * If the user doesn't exist in the games DB yet, it will be created automatically on first call.
-	 *
-	 * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-	 *
-	 * **Response** `GamesApiResponse<GamePickUserInfo>`:
-	 * - `errCode` - 0 on success
-	 * - `data`:
-	 *   - `ext_user_id` - External user ID (Smartico internal numeric ID)
-	 *   - `int_user_id` - Internal user ID within the games system
-	 *   - `public_username` - Display name
-	 *   - `avatar_url` - User's avatar image URL
-	 *   - `last_wallet_sync_time` - Last time the user's balance was synced from Smartico
-	 *   - `ach_points_balance` - User's current points balance
-	 *   - `ach_gems_balance` - User's current gems balance
-	 *   - `ach_diamonds_balance` - User's current diamonds balance
-	 *   - `pubic_username_set` - Whether the user has set a custom username
-	 *
-	 * **Example**:
+	 * Returns the current user's profile within the Game Pick system — display
+	 * name, avatar, balances, and last wallet-sync timestamp. The Game Pick server
+	 * maintains its own user record that mirrors the user's Smartico balances; the
+	 * mirror is updated at most once per minute, so `last_wallet_sync_time` tells
+	 * the consumer how stale the balances on the response are.
+	 *
+	 * On the user's first call for a given game, the Game Pick server lazily
+	 * provisions a user record — so this method doubles as a "register the user
+	 * with this game" call.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 *
+	 * **Balance freshness**
+	 * The balances returned here are the cached mirror — at most ~1 minute stale.
+	 * For an up-to-the-second view of Points / Gems / Diamonds, read from
+	 * {@link getUserProfile} instead. Use this method's balances only for
+	 * in-Game-Pick display.
+	 *
+	 * **Error codes** (in `errCode`)
+	 * - `0` — success.
+	 * - `100002` — template not found.
+	 * - `100000` — auth hash invalid.
+	 * - `100004` — generic server error.
+	 *
+	 * **Refresh**
+	 * - No cache. Server-side mirror refreshes at most every 60 s.
+	 * - No push subscription.
+	 *
+	 * **Visitor mode**: not supported.
+	 *
+	 * **UI guidance**: see [UI Guide — `gamePickGetUserInfo`](../../docs/ui/gamepick/UIGuide_gamePickGetUserInfo.md).
+	 *
+	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @returns Wrapped {@link GamesApiResponse} of {@link GamePickUserInfo}.
+	 *
+	 * @example
+	 * ```ts
+	 * const r = await window._smartico.api.gamePickGetUserInfo({ saw_template_id: 1083 });
+	 *
+	 * if (r.errCode === 0 && r.data) {
+	 *     console.log('[smartico] render Game Pick header — name:', r.data.public_username, '— points:', r.data.ach_points_balance, '— synced:', r.data.last_wallet_sync_time);
+	 * }
 	 * ```
-	 * _smartico.api.gamePickGetUserInfo({
-	 *      saw_template_id: 1083,
-	 * }).then((result) => {
-	 *      console.log(result.data.public_username, result.data.ach_points_balance);
-	 * });
-	 * ```
-	 *
-	 * **Visitor mode: not supported**
 	 */
 	public async gamePickGetUserInfo(props: GamePickRequestParams): Promise<GamesApiResponse<GamePickUserInfo>> {
 		if (!props.saw_template_id) {
@@ -296,38 +525,56 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	}
 
 	/**
-	 * Returns the game configuration and the list of all rounds for the specified MatchX or Quiz game.
-	 * Includes the SAW template definition, label settings, and round metadata (without events).
-	 *
-	 * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-	 *
-	 * **Response** `GamesApiResponse<GamePickGameInfo>`:
-	 * - `errCode` - 0 on success
-	 * - `data`:
-	 *   - `sawTemplate` - Game template configuration including:
-	 *     - `saw_template_id`, `saw_game_type_id` (6 = MatchX/Quiz)
-	 *     - `saw_template_ui_definition` - UI settings (name, ranking options, ask_for_username, etc.)
-	 *     - `saw_buyin_type_id` - Cost type (1=Free, 2=Points, 3=Gems, 4=Diamonds, 5=Spins)
-	 *     - `buyin_cost_points` - Cost per attempt
-	 *     - `spin_count` - Available attempts for the current user
-	 *   - `allRounds[]` - List of all rounds (metadata only, no events), each with:
-	 *     - `round_id`, `round_name`, `round_description`
-	 *     - `open_date`, `last_bet_date` - Timestamps (ms)
-	 *     - `is_active_now`, `is_resolved`, `round_status_id`
-	 *   - `labelInfo` - Label/brand configuration and settings
-	 *
-	 * **Example**:
+	 * Returns the game template configuration plus a metadata listing of every
+	 * round (without events). Use to power the game's welcome / lobby screen —
+	 * shows the template name, buy-in cost, the user's remaining attempts, and
+	 * the full round list.
+	 *
+	 * The `allRounds[]` here is a lightweight metadata-only view — to render
+	 * predictions or leaderboards, call {@link gamePickGetActiveRound} /
+	 * {@link gamePickGetActiveRounds} / {@link gamePickGetBoard} for the rounds
+	 * the user actually opens.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 *
+	 * **Buy-in semantics**
+	 * The `sawTemplate.saw_buyin_type_id` value determines which currency is
+	 * deducted on the user's first prediction in any round:
+	 * - Free — no deduction.
+	 * - Points — `buyin_cost_points` deducted from the user's points balance.
+	 * - Gems — deducted from the user's gems balance.
+	 * - Diamonds — deducted from the user's diamonds balance.
+	 * - Spins — one spin counted from `spin_count`.
+	 *
+	 * **Error codes** (in `errCode`)
+	 * - `0` — success.
+	 * - `100002` — template not found.
+	 * - `100000` — auth hash invalid.
+	 * - `100004` — generic server error.
+	 *
+	 * **Refresh**
+	 * - No cache.
+	 * - No push subscription. Re-call after a successful
+	 *   {@link gamePickSubmitSelection} to refresh `spin_count`.
+	 *
+	 * **Visitor mode**: not supported.
+	 *
+	 * **UI guidance**: see [UI Guide — `gamePickGetGameInfo`](../../docs/ui/gamepick/UIGuide_gamePickGetGameInfo.md).
+	 *
+	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @returns Wrapped {@link GamesApiResponse} of {@link GamePickGameInfo}.
+	 *
+	 * @example
+	 * ```ts
+	 * const r = await window._smartico.api.gamePickGetGameInfo({ saw_template_id: 1189 });
+	 *
+	 * if (r.errCode === 0 && r.data) {
+	 *     console.log('[smartico] render Game Pick lobby — title:', r.data.sawTemplate.saw_template_ui_definition.name);
+	 *     console.log('[smartico] rounds available:', r.data.allRounds.length, '— buy-in type:', r.data.sawTemplate.saw_buyin_type_id, 'cost:', r.data.sawTemplate.buyin_cost_points);
+	 * }
 	 * ```
-	 * _smartico.api.gamePickGetGameInfo({
-	 *      saw_template_id: 1189,
-	 * }).then((result) => {
-	 *      console.log(result.data.sawTemplate.saw_template_ui_definition.name);
-	 *      console.log('Rounds:', result.data.allRounds.length);
-	 *      console.log('Buy-in type:', result.data.sawTemplate.saw_buyin_type_id);
-	 * });
-	 * ```
-	 *
-	 * **Visitor mode: not supported**
 	 */
 	public async gamePickGetGameInfo(props: GamePickRequestParams): Promise<GamesApiResponse<GamePickGameInfo>> {
 		if (!props.saw_template_id) {
@@ -337,35 +584,73 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	}
 
 	/**
-	 * Returns round data with events and picks for a specific user (identified by their internal user ID).
-	 * Useful for viewing another user's predictions from the leaderboard.
-	 * The `int_user_id` can be obtained from the `gamePickGetBoard` response (`users[].int_user_id`).
-	 *
-	 * @param props.saw_template_id - The ID of the MatchX or Quiz game template
-	 * @param props.round_id - The round to get info for
-	 * @param props.int_user_id - Internal user ID of the player whose predictions to view (from leaderboard data)
-	 *
-	 * **Response** `GamesApiResponse<GamePickRound>`:
-	 * - `errCode` - 0 on success
-	 * - `data` - Round object with the target user's selections.
-	 *   Same structure as `gamePickGetActiveRound`, but `user_selection`/`team1_user_selection`/`team2_user_selection`
-	 *   fields on events reflect the specified user's picks instead of the current user's.
-	 *   Events also include `resolution_type_id` (0=None, 2=Lost, 3=PartialWin, 4=FullWin) showing how each prediction was scored
-	 *
-	 * **Example**:
-	 * ```
-	 * _smartico.api.gamePickGetRoundInfoForUser({
-	 *      saw_template_id: 1083,
-	 *      round_id: 31652,
-	 *      int_user_id: 65653810,
-	 * }).then((result) => {
-	 *      result.data.events.forEach(e => {
-	 *          console.log(e.event_meta.team1_name, 'vs', e.event_meta.team2_name, '→', e.user_selection);
-	 *      });
+	 * Returns a round with another player's predictions instead of the current
+	 * user's. The target player is identified by `int_user_id` (the Game Pick
+	 * system's internal user ID, obtained from {@link gamePickGetBoard}'s
+	 * `users[].int_user_id`).
+	 *
+	 * Use to power "view this player's picks" affordances opened from leaderboard
+	 * rows — community / social inspection of how a top-ranked user predicted.
+	 *
+	 * @remarks
+	 * **Preconditions**
+	 * - User must be authenticated. Visitor mode not supported.
+	 * - `saw_template_id`, `round_id`, and `int_user_id` are all mandatory — SDK
+	 *   throws synchronously if any is missing.
+	 * - `int_user_id` must come from a leaderboard fetch in the same game
+	 *   template; it is stable within a template but not portable across
+	 *   templates.
+	 *
+	 * **Shape vs `gamePickGetActiveRound`**
+	 * Same {@link GamePickRound} structure, but `user_selection` /
+	 * `team1_user_selection` / `team2_user_selection` reflect the TARGET user's
+	 * predictions instead of the caller's. Each event still carries its own
+	 * `resolution_type_id` (see {@link GamePickResolutionType}) so the UI can
+	 * render result badges per pick.
+	 *
+	 * **Error codes** (in `errCode`)
+	 * - `0` — success.
+	 * - `4` — round / event / user not found.
+	 * - `100002` — template not found.
+	 * - `100000` — auth hash invalid.
+	 * - `100004` — generic server error.
+	 *
+	 * **Refresh**
+	 * - No cache. Re-call when opening a different leaderboard row's
+	 *   "view picks" modal.
+	 * - No push subscription.
+	 *
+	 * **Visitor mode**: not supported.
+	 *
+	 * **UI guidance**: see [UI Guide — `gamePickGetRoundInfoForUser`](../../docs/ui/gamepick/UIGuide_gamePickGetRoundInfoForUser.md).
+	 *
+	 * @param props.saw_template_id  ID of the MatchX or Quiz game template.
+	 * @param props.round_id         ID of the round to inspect.
+	 * @param props.int_user_id      Internal user ID from
+	 *                                `gamePickGetBoard.users[].int_user_id`.
+	 * @returns Wrapped {@link GamesApiResponse} with the target user's
+	 * {@link GamePickRound}.
+	 *
+	 * @example
+	 * ```ts
+	 * const board = await window._smartico.api.gamePickGetBoard({
+	 *     saw_template_id: 1083, round_id: 31652,
 	 * });
-	 * ```
+	 * const topPlayer = board.data?.users?.[0];
+	 * if (!topPlayer) return;
 	 *
-	 * **Visitor mode: not supported**
+	 * const r = await window._smartico.api.gamePickGetRoundInfoForUser({
+	 *     saw_template_id: 1083,
+	 *     round_id:        31652,
+	 *     int_user_id:     topPlayer.int_user_id,
+	 * });
+	 *
+	 * if (r.errCode === 0 && r.data) {
+	 *     for (const ev of r.data.events) {
+	 *         console.log('[smartico] render row —', ev.event_meta.team1_name, 'vs', ev.event_meta.team2_name, '— picked:', ev.user_selection, '— resolution:', ev.resolution_type_id);
+	 *     }
+	 * }
+	 * ```
 	 */
 	public async gamePickGetRoundInfoForUser(props: GamePickRoundRequestParams & { int_user_id: number }): Promise<GamesApiResponse<GamePickRound>> {
 		if (!props.saw_template_id) {